Metadata-Version: 2.4
Name: plot3d-vehicle-sensor
Version: 0.0.3
Summary: Headless and optional UI 3D vehicle/sensor orientation plotting based on tftree-manager workspaces
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: tftree-manager>=0.1.5
Requires-Dist: minieye-runtime-config>=0.0.5
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: ui
Requires-Dist: PySide6; extra == "ui"

# plot3d-vehicle-sensor

`plot3d-vehicle-sensor` renders 3D vehicle/sensor orientation plots from a
D03 `tftree-manager` workspace. It accepts either an existing
`TFTreeWorkspace` instance or a YAML workspace directory.

Version: 0.0.3

## Features

- Builds sensor records with D03 `TFTreeWorkspace`, `TransformQueryService`,
  and compute output mode.
- Classifies sensor groups from D13 `minieye-runtime-config`
  `[sensor_categories]` exact frame names; unmatched frames are shown as `other`.
- Provides headless matplotlib rendering that can save PNG files.
- Provides a matplotlib plotting helper for embedding in other tools.
- Provides an optional PySide6 window entrypoint with D03-style plot controls.
- Uses orthographic projection by default for calibration checks; perspective
  display is available when explicitly requested.
- Installs the CLI command `plot3d-vehicle-sensor <yaml_dir>`.

## Python API

```python
from plot3d_vehicle_sensor import build_sensor_records, render_sensor_orientations

records = build_sensor_records(yaml_dir="/path/to/yaml", root="vehicle")
context = render_sensor_orientations(
    yaml_dir="/path/to/yaml",
    root="vehicle",
    save_path="sensors.png",
    show=False,
    projection_type="ortho",
    options={
        "category_options": {"lidar": {"main_axis": "x+", "show_aux_axes": True}},
        "visible_frames": {"at128p_front_lidar": True},
        "label_font_size": 10,
    },
)
```

## CLI

```bash
plot3d-vehicle-sensor /path/to/yaml --root vehicle --output sensors.png --no-show
plot3d-vehicle-sensor /path/to/yaml --projection persp
```

`--projection` accepts `ortho` or `persp` and defaults to `ortho`.

## Optional UI

```python
from plot3d_vehicle_sensor import SensorOrientationPlotAction, open_sensor_orientation_window

open_sensor_orientation_window(
    yaml_dir="/path/to/yaml",
    root="vehicle",
    actions=[
        SensorOrientationPlotAction("自定义按钮", lambda context: print(len(context.records))),
    ],
)
```

The UI includes the D03 3D window controls: global name/axis/aux/cursor
settings, per-sensor visibility, vehicle model dimensions including `custom`
vehicle type, a `显示模式` dropdown for `正交`/`透视`, six view preset buttons,
image save, custom actions, close, and mouse-wheel zoom. Projection mode only
changes display projection; it does not modify extrinsics, coordinates, vehicle
dimensions, or sensor placement. The `ui` extra remains optional; headless
rendering does not require PySide6.

Install the `ui` extra to use the PySide6 window:

```bash
pip install 'plot3d-vehicle-sensor[ui]'
```

## 设计原则

- [版本无关设计原则](../../design_principle.md)
