Metadata-Version: 2.4
Name: hello-robot-stretch4-urdf
Version: 2026.7.31
Summary: Stretch 4 URDF
Author-email: "Hello Robot Inc." <support@hello-robot.com>
Project-URL: Repository, https://github.com/hello-robot/stretch4_urdf
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: yourdfpy>=0.0.58
Requires-Dist: trimesh
Requires-Dist: numpy
Requires-Dist: pyyaml
Requires-Dist: xacro<3.0,>=2.1
Provides-Extra: robot
Requires-Dist: hello-robot-stretch4-body; extra == "robot"
Provides-Extra: preprocessing
Requires-Dist: open3d; extra == "preprocessing"
Dynamic: license-file

# Overview

This package provides robot description and mesh files for Stretch 4, as well as code for manipulating the kinematic description (e.g. adding virtual joints) and exporting for use in other programs (e.g. ROS2, pinocchio). The repository for Stretch 3 and earlier hardware versions can be found in [stretch\_urdf](https://github.com/hello-robot/stretch_urdf). This package can be installed by:

```
python3 -m pip install -U hello-robot-stretch4-urdf
```

<div align="center"><img src=".gitbook/assets/stretch4_robot_model.png" alt="Stretch 4 robot model" width="50%"></div>

<p align="center"> <br> </p>

## Details

The URDF and meshes are installed to your Python site directory. You can load them dynamically using:

```python
from stretch4_urdf import get_urdf

# configure the specifications for your robot
model_name = "SE4"
batch_name = "francis"
tool_name = "eoa_wrist_dw4_tool_sg4"

print(get_urdf(
    model_name=model_name,
    batch_name=batch_name,
    tool_name=tool_name,
))
```

Currently supported options for the `model_name`, `batch_name`, and `tool_name` are:

```python
supported_model_names = ["SE4"]
supported_batch_names = ["francis"]
supported_tool_names = ["eoa_wrist_dw4_tool_sg4"]
```

A single composable xacro combines a robot's base model with its attached tool. Util functions will handle processing the xacro file and return the URDF for the robot's current configuration:

```python
from stretch4_urdf import get_urdf_from_robot_params
urdf_string = get_urdf_from_robot_params() # store the urdf contents in a str variable
urdf_filepath = get_urdf_from_robot_params(out_dir="/tmp") # save the urdf to a file in the /tmp directory
```

You can also load accessory URDFs via:

```python
from stretch4_urdf import get_accessory

dock_urdf = get_accessory("docking_station")
print(dock_urdf)
```

Utility methods are provided to extract 4x4 coordinate transforms:

```python
from stretch4_urdf import get_transform

# Get the 4x4 transform between two frames
T_dock_to_leftaruco = get_transform(dock_urdf, frame_to="left_aruco_marker_link", frame_from="docking_station_link")
print(T_dock_to_leftaruco)
```
## Tools

### URDF Visualization

The `stretch_urdf_viz` tool allows you to visualize the robot's URDF in [Rerun](https://rerun.io/).

```bash
stretch_urdf_viz
```

By default, the tool will visualize the robot's nominal (uncalibrated) URDF. If the robot has been calibrated, the calibrated URDF will be automatically overlaid in green.

Key features:
- **Calibrated vs Uncalibrated**: Automatically shows both if calibration data is available.
- **Toggles**: Meshes, coordinate frames (TFs), and labels are organized into separate trees in Rerun, allowing them to be toggled on/off easily to reduce clutter.

Options:
- `--model`: Specify the robot model (e.g., `SE4`).
- `--batch`: Specify the robot batch (e.g., `francis`).
- `--tool`: Specify the end-of-arm tool (e.g., `eoa_wrist_dw4_tool_sg4`).

## Bringing in URDF's from CAD

The package follows a strict directory strucutre:

```yaml
> {model}_{batch}
    > meshes
        visual and collision mesh STL files
    > xacro
        stretch_main.xacro
```

```yaml
> {model}_tools
    > {tool_name}
        > meshes
            visual and collision mesh STL files
        {tool_name}.urdf
```

The URDF and meshes from the CAD model are added to the {model}\_{batch} base directory and meshes folder. From there, `utils/preprocessing/process_new_robot_model.py` creates the stretch\_main.xacro file and necessary collision meshes for the batch. See the urdf\_conventions.md for the specifics of this processing step.

A directory is created for each new tool, with the urdf in the base directory and a folder for meshes. `utils/preprocessing/process_new_tool.py` is then used to add the necessary edits to the urdf and generate collision meshes.

## Documentation

The following files provide deeper documentation on various parts of the system:

| Primer                                                    | Description                                                                                               |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [Batches](stretch4_urdf/batches.md)                       | Explains URDF batch organization, compiling the URDF dynamically, and how to add new batch models.        |
| [End Effectors](stretch4_urdf/SE4_tools/end_effectors.md) | Outlines the available end effector tools and provides instructions on how to add new tools to the robot. |
| [URDF Conventions](./urdf_conventions.md) | Outlines which conventions are used in the Stretch 4 URDF. |
| [Calibration](stretch4_urdf/calibration.md) | Explains how static calibration values are applied to the URDF at load time. |
| [Kinematic Changes](stretch4_urdf/kinematic_changes.md) | Tracks breaking kinematic and coordinate frame changes for Stretch 4. |
| [Camera Orientations](stretch4_urdf/camera_orientations.md) | Deep dive into the camera coordinate systems, mounting angles, and optical frame conventions. |
