From f638f8000e77a6807af5c7873a5ad7b3bbc2ea55 Mon Sep 17 00:00:00 2001 From: "komment-ai[bot]" <122626893+komment-ai[bot]@users.noreply.github.com> Date: Sun, 8 Sep 2024 16:03:38 +0000 Subject: [PATCH] Added comments to 11 items across 2 files --- examples/hand_guide.py | 85 ++++++++++++++++++++---------------------- setup.py | 59 +++++++++++++++-------------- 2 files changed, 71 insertions(+), 73 deletions(-) diff --git a/examples/hand_guide.py b/examples/hand_guide.py index 066fc55..b15c234 100644 --- a/examples/hand_guide.py +++ b/examples/hand_guide.py @@ -20,42 +20,37 @@ class HandGuideClient(fri.LBRClient): """ - Initializes and manages a robotic arm's state, commanding its position based - on estimated joint states and external wrenches. It updates the robot's pose, - checks command mode, and filters wrench estimates to ensure smooth motion control. + Initializes a hand guide client for interacting with a robot arm. It estimates + joint states and wrenches, filters sensor data, and updates robot commands + based on the controller's output to maintain stable movement. Attributes: - controller (AdmittanceController|None): Initialized with an instance of - AdmittanceController in the constructor. It represents a controller - used for controlling the robot's joints based on estimated wrenches - and other factors. - joint_state_estimator (JointStateEstimator|None): Initialized with the - instance itself as its argument, indicating it's responsible for - estimating joint states based on current conditions. + controller (AdmittanceController|None): Initialized with lbr_ver as a + parameter in its constructor method, likely controlling the robot's admittance. + joint_state_estimator (JointStateEstimator): Initialized with a reference + to the current `HandGuideClient` instance as its argument. It estimates + joint states of the robot. external_torque_estimator (FRIExternalTorqueEstimator|None): Initialized - with its constructor being called on self, which suggests it estimates - external torques acting on the robot. - wrench_estimator (WrenchEstimatorTaskOffset|JointStateEstimator|FRIExternalTorqueEstimator): - Associated with a robot, ee link, and joint state estimator. It estimates - task-space forces and torques from joint sensor readings and external - torque estimations. - wrench_filter (ExponentialStateFilter): Used to filter wrench data from - the `WrenchEstimatorTaskOffset`. It appears to be a state estimation - method to provide more accurate results. + with a reference to the client object itself during construction. + wrench_estimator (WrenchEstimatorTaskOffset|None): Initialized with four + parameters: the instance itself, its associated joint state estimator, + external torque estimator, and controller. It filters and estimates + wrench values based on task offsets. + wrench_filter (ExponentialStateFilter): Used to filter the wrench estimates + from the WrenchEstimatorTaskOffset instance associated with it. """ def __init__(self, lbr_ver): """ - Initializes objects for admittance control, joint state estimation, external - torque estimation, wrench estimation, and exponential state filtering based - on provided parameters. It also establishes relationships between these - components for coordinated functioning. + Initializes various components necessary for the controller and estimators, + including an admittance controller, joint state estimator, external torque + estimator, wrench estimator, and wrench filter. These are likely used to + control a robot arm's movements. Args: - lbr_ver (str | int): Used to specify the version or identifier of the - robot. This value is passed to the AdmittanceController class - during initialization. It appears to be related to the robotic - arm's model. + lbr_ver (str | int | float): Used to specify a version or other version + information about the LBR (Lightweight Robot) being controlled by + this class instance. """ super().__init__() @@ -82,9 +77,10 @@ def onStateChange(self, old_state, new_state): def waitForCommand(self): """ - Waits for a command from the client to be executed. It checks if the current - client mode matches POSITION, updates the wrench estimator, retrieves the - current joint position, and executes the command position. + Checks if the robot's client command mode is set to POSITION, otherwise + it prints an error message and exits. If the mode is correct, it retrieves + the current joint position from the robot state and calls the `command_position` + method. """ if self.robotState().getClientCommandMode() != POSITION: @@ -93,15 +89,14 @@ def waitForCommand(self): ) raise SystemExit - self.wrench_estimator.update() self.q = self.robotState().getIpoJointPosition() self.command_position() def command(self): """ - Updates robot position commands by filtering and processing wrench data - from the wrench estimator, then calls the `controller` function to compute - new joint positions. It also sets the joint position command of the robot. + Updates the robot's joint position based on estimated wrench and filtered + feedback, using a controller to compute the new position. It checks if the + estimator is ready before proceeding with the update process. """ if not self.wrench_estimator.ready(): @@ -125,13 +120,14 @@ def command(self): def args_factory(): """ - Creates an instance of the ArgumentParser class and defines arguments for - parsing command-line input. It returns a Namespace object containing user-specified - values for hostname, port, and LBR Med version number. + Parses command-line arguments using argparse. It defines three arguments: + hostname, port, and lbr-ver, which are then returned as parsed arguments. The + lbr-ver argument requires a specific integer value from the list [7, 14] and + is mandatory. Returns: - argparseNamespace: An object containing arguments parsed from the command - line. This object holds attributes for `hostname`, `port`, and `lbr_ver`. + argparseNamespace: An instance that stores the parsed command-line arguments + as attributes, allowing access to them as a dictionary-like object. """ parser = argparse.ArgumentParser(description="LRBJointSineOverlay example.") @@ -162,13 +158,14 @@ def args_factory(): def main(): """ - Initializes a connection to a KUKA Sunrise controller, attempts to establish - communication, and repeatedly polls the robot's state until idle or an error - occurs. It also handles keyboard interrupts and system exits before disconnecting - from the controller and terminating. + Initializes a FRI client, connects to a KUKA Sunrise controller, and executes + a sequence of steps. It continuously checks if the robot session is idle; if + so, it breaks out of the loop. The function gracefully handles keyboard + interrupts and system exits. Returns: - int: 1 when connection to KUKA Sunrise controller fails, and 0 otherwise. + int|None: 1 when connection to KUKA Sunrise controller fails or 0 on + successful execution. """ print("Running FRI Version:", fri.FRI_CLIENT_VERSION) diff --git a/setup.py b/setup.py index 476967a..37cb424 100644 --- a/setup.py +++ b/setup.py @@ -11,10 +11,10 @@ # Read the configuration settings class UserInputRequired(Exception): """ - Defines a custom exception to handle situations where user input is missing - or incomplete. It inherits from Python's built-in `Exception` class and takes - an error message as an argument, allowing for customizable error handling and - messaging. + Defines a custom exception that signals the need for user input to proceed + with a particular operation or action. It serves as a signal to handle missing + or invalid user data, ensuring program flow continues after receiving required + input from users. """ def __init__(self, msg): @@ -41,30 +41,30 @@ def __init__(self, msg): # If you need multiple extensions, see scikit-build. class CMakeExtension(Extension): """ - Initializes a C extension for use with Pybind11. It sets up the extension's - name and source directory, resolving the source directory to an absolute path - using Python's `os.fspath` and `Path.resolve` functions. + Initializes a CMake extension project with given name and source directory + path. It sets up the basic structure for a CMake build, allowing sources to + be added later. The `sourcedir` parameter is resolved to an absolute file + system path. Attributes: - sourcedir (Path|str): Resolved to a string path using - `os.fspath(Path(sourcedir).resolve())`. It represents the directory - where sources for the CMake extension are located. + sourcedir (osPathLike[str]|str): Set to a normalized path string. It stores + the source directory for the extension. This value can be obtained + from a Path object, which provides file system operations. """ def __init__(self, name: str, sourcedir: str = "") -> None: """ - Initializes an instance of the class with a name and optionally a sourcedir. - It calls the superclass's `__init__` method to set up basic attributes, - then sets the sourcedir attribute to its resolved absolute path. + Initializes an instance with a specified name and optionally a sourcedir + path. The `super().__init__` call creates a base Extension instance with + the given name, while also initializing a sources list. The sourcedir path + is resolved and stored in self.sourcedir. Args: - name (str): Required to be passed during object instantiation. It is - expected to be a string representing the name associated with the - instance being created. - sourcedir (str): Initialized with an empty string. It represents the - directory where source files are located. The `os.fspath` and - `Path.resolve()` functions are used to ensure the path is resolved - and converted to a string. + name (str): Required for initialization. It represents the name of an + object being created and will be used as its identifier. + sourcedir (str): Optional, as indicated by its default value. It + represents the source directory path that can be resolved to an + absolute path using os.fspath and Path.resolve. """ super().__init__(name, sources=[]) @@ -73,20 +73,21 @@ def __init__(self, name: str, sourcedir: str = "") -> None: class CMakeBuild(build_ext): """ - Extends the `build_ext` class to build C++ extensions using the CMake build - system, handling various configuration options and environmental variables for - cross-platform compatibility. + Extends the `build_ext` class from Python's `setuptools` package to provide + custom CMake-based build logic for extension modules. It generates and builds + CMake project files, incorporating environment variables and project-specific + settings. """ def build_extension(self, ext: CMakeExtension) -> None: """ - Configures and builds a CMake-based extension using Python's subprocess - module, invoking the cmake command to generate build files and then running - the build process according to the specified configuration. + Builds and configures a CMake-based extension using specified environment + variables, compiler types, and configuration settings to generate native + libraries for various platforms and architectures. Args: - ext (CMakeExtension): Required for the function to execute. It represents - an extension being built with CMake. + ext (CMakeExtension): Expected to be a specific extension that needs + to be built. """ # Must be in this form due to bug in .resolve() only fixed in Python 3.10+ @@ -192,7 +193,7 @@ def build_extension(self, ext: CMakeExtension) -> None: setup( name="pyfri", - version="1.2.0", + version="1.2.1", author="Christopher E. Mower, Martin Huber", author_email="christopher.mower@kcl.ac.uk, m.huber_1994@hotmail.de", description="Python bindings for the FRI Client SDK library.",