chore: release v0.4.0

Author: motphys-developers

.gitignore

@@ -3,9 +3,9 @@ __pycache__/
 .mypy_cache/
 .pytest_cache/
 .ruff_cache/
-.pdm-python
 .python-version
-.egg-info/
+*.egg-info/
+.venv
 
 docs/source/index.md
 docs/source/api_reference

README.md

@@ -29,9 +29,9 @@
 
 ## 🚀 快速开始
 
-> 以下示例使用了 Python 项目管理工具：[PDM](https://pdm-project.org/)
+> 以下示例使用了 Python 项目管理工具：[UV](https://docs.astral.sh/uv/)
 > 
-> 在开始之前，请先[安装](https://pdm-project.org/en/latest/#installation)该工具。
+> 在开始之前，请先[安装](https://docs.astral.sh/uv/getting-started/installation/)该工具。
 
 ### 1. 克隆仓库:
 
@@ -43,23 +43,17 @@ cd motrixsim-docs
 git lfs pull
 ```
 
-### 2. 创建虚拟环境
-
-```bash
-pdm use 3.10
-```
-
-### 3. 安装依赖
+### 2. 安装依赖
 
 ```
 # 检查更新并安装依赖
-pdm install -G examples -v
+uv sync --extra examples --upgrade
 
 # 不检查更新，直接安装依赖
-pdm sync -G examples -v
+uv sync --extra examples
 ```
 
-### 4. 执行对比与示例
+### 3. 执行对比与示例
 
 > 参考 [文档](https://motrixsim.readthedocs.io) 中的说明
 

docs/CLAUDE.md

@@ -56,7 +56,7 @@ This is the documentation project for MotrixSim, a high-performance physics simu
   - sphinx-design (design components)
   - sphinx_copybutton (code copy functionality)
 - **Language Support**: Chinese (zh_CN) and English with automatic content copying
-- **Autodoc**: Automatic API documentation generation from Python docstrings
+- **Autodoc**: Automatic API documentation generation
 
 ### Dependencies
 Documentation dependencies are managed in the parent `pyproject.toml`:
@@ -82,6 +82,15 @@ docs = [
 - **Code Examples**: Include practical code examples with proper syntax highlighting
 - **API Documentation**: Use NumPy/Google style docstrings for autodoc generation
 
+### Important: Document Structure
+**Critical**: The documentation has a specific structure that must be followed:
+
+- **`source/user_guide/`**: This directory is **auto-generated** during build. **DO NOT** edit files here directly.
+- **`source/zh_CN/`**: This directory contains the **manually written** Chinese documentation. All edits should be made here.
+- **`source/en/`**: This directory contains the **manually written** English documentation.
+
+The build system automatically copies content from language-specific directories (`zh_CN/`, `en/`) to the main structure during compilation. Always edit the source files in the appropriate language directory, not the auto-generated files.
+
 ### Media and Assets
 - **Videos**: Embedded using sphinxcontrib-video extension
 - **Images**: Stored in `_static/images/` with poster images for videos
@@ -113,12 +122,6 @@ docs = [
 3. Verify multilingual content works correctly
 4. Test all embedded media and interactive elements
 
-## File Naming Conventions
-- Use lowercase with underscores for file names
-- Index files should be named `index.md`
-- API documentation files should match module names
-- Media files should be descriptive and use appropriate extensions
-
 ## Integration Notes
 - This documentation project is part of the larger motrixsim-py package
 - The build system automatically detects and documents the motrixsim package

docs/source/en/user_guide/getting_started/mjcf.md

@@ -28,8 +28,8 @@ MJCF contains a rich set of tags and attributes. This section lists the current
   - **Planned Attributes**
   - **Unsupported Attributes**
 * - option
-  - timestep, gravity, iterations, tolerance
-  - apirate, wind, magnetic, density, viscosity, o_margin, o_solref, o_solimp, o_friction, actuatorgroupdisable
+  - timestep, gravity, iterations, tolerance, o_margin, o_solref, o_solimp, o_friction
+  - apirate, wind, magnetic, density, viscosity, actuatorgroupdisable
   - impratio, integrator, cone, jacobian, solver, ls_iterations, ls_tolerance, noslip_iterations, noslip_tolerance, ccd_iterations, ccd_tolerance, sdf_iterations,  sdf_initpoints
 * - compiler
   - autolimits, angle, eulerseq, meshdir, texturedir, assetdir

docs/source/en/user_guide/index.md

@@ -30,7 +30,7 @@ main_function/render
 
 ```{toctree}
 :caption: Kinematics
-:maxdepth: 1
+:maxdepth: 2
 kinematics/body
 kinematics/floating_base
 kinematics/joint

docs/source/en/user_guide/kinematics/geometry.md

@@ -30,7 +30,7 @@ Once you obtain a Geom object, you can read information such as its position, or
 You can run a simple example of Geom API usage with:
 
 ```bash
-pdm run examples/geom.py
+uv run examples/geom.py
 ```
 
 See the source code at [`examples/geom.py`](../../../../examples/geom.py)。
@@ -39,3 +39,9 @@ See the source code at [`examples/geom.py`](../../../../examples/geom.py)。
 [`model.geoms`]: motrixsim.SceneModel.geoms
 [`model.get_geom(key)`]: motrixsim.SceneModel.get_geom
 [`Geom API`]: motrixsim.Geom
+
+```{toctree}
+:maxdepth: 1
+geometry/hfield
+
+```

docs/source/en/user_guide/kinematics/geometry/hfield.md

@@ -0,0 +1,246 @@
+# Height Fields (HField)
+
+Height Fields (HField) are an efficient geometry type for representing terrain surfaces. They store elevation information through 2D grid data, providing realistic physical collision responses for robot simulation, terrain following, and surface interaction.
+
+## Height Field Features
+
+Height fields offer the following advantages:
+
+-   **Efficient Storage**: Uses regular grids to store elevation data with low memory footprint
+-   **Fast Collision Detection**: Grid-based spatial partitioning algorithms provide efficient collision queries
+-   **Realistic Terrain Simulation**: Supports complex terrain features such as hillsides, ravines, plains, etc.
+-   **Large-scale Scenes**: Suitable for representing large terrain areas, commonly used in outdoor robot simulation
+
+## MJCF Configuration
+
+In MJCF files, height fields are defined using the `<hfield>` tag, supporting three data source methods:
+
+### 1. Inline Elevation Data
+
+Directly specify elevation data matrix in XML:
+
+```xml
+<asset>
+    <hfield name="terrain1"
+            nrow="15"
+            ncol="15"
+            elevation="0.0 0.43 0.78 0.97 ..."
+            size="5 5 2 0.1"/>
+</asset>
+```
+
+### 2. PNG Image Files
+
+Use PNG images as elevation data source (recommended for visual terrain):
+
+```xml
+<asset>
+    <hfield name="png_terrain"
+            file="terrain.png"
+            content_type="image/png"
+            size="10 10 3 0.2"/>
+</asset>
+```
+
+**Notes:**
+
+-   PNG images are automatically converted to grayscale
+-   White pixels correspond to high elevation, black pixels to low elevation
+-   Intensity values are used as elevation data and normalized to [0, 1] range
+
+### 3. Custom Binary Files
+
+Use MuJoCo custom binary format:
+
+```xml
+<asset>
+    <hfield name="binary_terrain"
+            file="terrain.hfield"
+            content_type="image/vnd.mujoco.hfield"
+            size="8 8 2.5 0.15"/>
+</asset>
+```
+
+**Binary file format:**
+
+-   File size: `4 × (2 + nrow × ncol)` bytes
+-   Structure:
+    -   `int32 nrow`: Number of rows
+    -   `int32 ncol`: Number of columns
+    -   `float32 data[nrow×ncol]`: Elevation data (row-major order)
+
+### MJCF Attribute Description
+
+| Attribute      | Type                     | Default  | Description                                                                                                                                         |
+| -------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`         | string                   | optional | Height field name for reference. If omitted and file name is specified, uses filename (without path and extension)                                  |
+| `content_type` | string                   | optional | **Currently ignored by MotrixSim**                                                                                                                  |
+| `file`         | string                   | optional | External file path. `.png` files are converted to grayscale, intensity values used as elevation data; other formats treated as custom binary format |
+| `nrow`         | integer                  | "0"      | Number of rows in elevation data matrix. Default 0 means load from file and automatically infer matrix size                                         |
+| `ncol`         | integer                  | "0"      | Number of columns in elevation data matrix                                                                                                          |
+| `elevation`    | float array (nrow×ncol)  | optional | Inline elevation data matrix. Data automatically normalized to [0, 1] range. Defaults to 0 if not provided                                          |
+| `size`         | float array (4 elements) | required | Physical dimensions: `[radius_x, radius_y, elevation_z, base_z]`                                                                                    |
+
+### Detailed size Attribute Description
+
+The `size` attribute contains four floats: `[radius_x, radius_y, elevation_z, base_z]`, with each parameter meaning:
+
+-   **radius_x**: Radius in X direction (half-width). Total width of height field on X axis is `2 × radius_x`
+-   **radius_y**: Radius in Y direction (half-length). Total length of height field on Y axis is `2 × radius_y`
+-   **elevation_z**: Maximum elevation. This value scales normalized [0-1] elevation data, so lowest point is at Z=0, highest point at Z=elevation_z
+-   **base_z**: Base depth. **Currently ignored by MotrixSim**
+
+**Important Notes:**
+
+-   Height fields are centered in the local coordinate system of the referencing geometry
+-   Elevation direction is +Z direction
+-   Unlike planes, height fields are treated as unions of regular geometry, with no concept of "below height field" - geometry is either inside or outside the height field
+-   Therefore, base parts must have non-zero thickness to avoid penetration issues
+
+**Example:**
+
+```xml
+<!-- Create a 10×10 unit height field with max elevation 2 units and base thickness 0.1 units -->
+<hfield name="terrain" size="5 5 2 0.1" nrow="50" ncol="50"/>
+```
+
+### Collision Detection Features
+
+Height field collision detection has the following important characteristics:
+
+**Collision Model:**
+
+-   Height fields are treated as unions of triangular prisms
+-   First select potentially colliding sub-grid prisms based on geometry bounding boxes
+-   Then use general convex colliders for precise collision calculation
+
+**Supported Collision Types:**
+
+-   ✅ Height field with sphere, capsule, cylinder, cube, polyhedron
+-   ❌ Height field with plane collision (not supported)
+-   ❌ Height field with other height field collision (not supported)
+
+For more detailed hfield field descriptions, please refer to the [MJCF official documentation](https://mujoco.readthedocs.io/en/3.3.7/XMLreference.html#asset-hfield).
+
+### Geometry Reference
+
+Use height fields in `<worldbody>`:
+
+```xml
+<worldbody>
+    <geom name="terrain" type="hfield" hfield="terrain1" material="ground_material"/>
+    <geom pos="10 0 0" name="terrain2" type="hfield" hfield="file_terrain" material="ground_material"/>
+</worldbody>
+```
+
+## Main Interfaces
+
+In MotrixSim, you can access HField objects through the following methods:
+
+-   [`model.num_hfields`]: Get the number of height fields in the current scene.
+-   [`model.get_hfield(name_or_index)`]: Get a specific height field object by name or index.
+
+### HField Object Properties
+
+After obtaining an HField object, you can access the following properties:
+
+```python
+hfield = model.get_hfield("terrain1")
+
+# Basic properties
+name = hfield.name          # Height field name
+nrow = hfield.nrow          # Number of grid rows
+ncol = hfield.ncol          # Number of grid columns
+bound = hfield.bound        # Bounding box [-x, -y, 0, x, y, z]
+
+# Elevation data
+height_matrix = hfield.height_matrix  # Complete elevation matrix (nrow × ncol)
+
+# Query elevation at specific point
+height = hfield.get(row=5, col=10)    # Get elevation at specified row and column
+```
+
+## Usage Examples
+
+### Basic Height Field Operations
+
+```{literalinclude} ../../../../../examples/hfield.py
+:language: python
+:dedent:
+:start-after: "# tag::basic_access"
+:end-before: "# end::basic_access"
+```
+
+### Elevation Data Analysis
+
+```{literalinclude} ../../../../../examples/hfield.py
+:language: python
+:dedent:
+:start-after: "# tag::height_analysis"
+:end-before: "# end::height_analysis"
+```
+
+### Complete Simulation Example
+
+```{literalinclude} ../../../../../examples/hfield.py
+:language: python
+:dedent:
+```
+
+Run the height field simulation example:
+
+```bash
+uv run examples/hfield.py
+```
+
+## File Format
+
+MotrixSim supports binary height field file format (`.hfield`):
+
+### File Structure
+
+-   **Header**: First 8 bytes
+    -   `nrow` (int32): Number of grid rows
+    -   `ncol` (int32): Number of grid columns
+-   **Data section**: Remaining bytes
+    -   Elevation data array (float32), length `nrow × ncol`
+
+### Generating Height Field Files
+
+You can create custom height field files using the following method:
+
+```python
+import numpy as np
+
+def create_hfield_file(filename, height_data):
+    """Create binary height field file"""
+    nrow, ncol = height_data.shape
+
+    with open(filename, 'wb') as f:
+        # Write header information
+        f.write(np.array([nrow, ncol], dtype=np.int32).tobytes())
+        # Write elevation data
+        f.write(height_data.astype(np.float32).tobytes())
+
+# Example: Create simple terrain
+x = np.linspace(-5, 5, 50)
+y = np.linspace(-5, 5, 50)
+X, Y = np.meshgrid(x, y)
+Z = 0.5 * np.sin(X) * np.cos(Y)  # Sine wave terrain
+
+create_hfield_file("custom_terrain.hfield", Z)
+```
+
+## API Reference
+
+For more HField-related APIs, please refer to:
+
+-   [`HField API`]: Complete height field class interface documentation
+-   [`SceneModel.get_hfield()`]: Method to get height field objects
+-   [`SceneModel.num_hfields`]: Get number of height fields
+
+[`model.num_hfields`]: motrixsim.SceneModel.num_hfields
+[`model.get_hfield(name_or_index)`]: motrixsim.SceneModel.get_hfield
+[`HField API`]: motrixsim.HField
+[`SceneModel.get_hfield()`]: motrixsim.SceneModel.get_hfield
+[`SceneModel.num_hfields`]: motrixsim.SceneModel.num_hfields

docs/source/en/user_guide/kinematics/link.md

@@ -29,7 +29,7 @@ Once you have a Link object, you can manipulate it using a variety of properties
 You can run a simple example demonstrating link API usage with:
 
 ```bash
-pdm run examples/link.py
+uv run examples/link.py
 ```
 
 See the source code at [`examples/link.py`](../../../../examples/link.py).