Metadata-Version: 2.4
Name: open3d-four-view
Version: 0.0.1
Summary: Render PCD point clouds into a single Open3D four-view merge PNG.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: Pillow
Requires-Dist: PyYAML
Requires-Dist: open3d
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# open3d-four-view

Render one PCD into a single 2x2 four-view PNG with Open3D. The package renders top, front, right, and oblique views in memory, then writes only the final merge image.

## Python API

```python
from open3d_four_view import render_pcd_merge_view

render_pcd_merge_view(
    "input.pcd",
    output_path="output.png",
    title="merge-view",
    overlay_info={
        "Viewpoint": "Merged four views",
        "car_model_id": "CAR001",
        "branch": "main",
        "commit": "abc123",
        "soc": "soc2",
    },
    color_legend={
        "at128p_front": {"rgb": [255, 0, 0]},
        "lidar_right": {"rgb": [0, 255, 0]},
    },
    gpu=True,
)
```

`output_path` has the highest priority and is used exactly. Without `output_path`, the default single-file output is `<input_dir>/<base>_merge.png`. With `output_dir`, the output is `<output_dir>/<base>_merge.png`.

`gpu=True` requests GPU graphics rendering through Open3D `OffscreenRenderer` when available. It does not enable Open3D CUDA tensor point-cloud processing.

## CLI

```bash
open3d-four-view --input_path input.pcd --output_path output.png
open3d-four-view --input_path input.pcd --output_path output.png --gpu
open3d-four-view --input_dir pcds --output_dir out --title merge-view
open3d-four-view --input_dir pcds --output_dir out --gpu
```

Overlay and legend data can be passed as JSON:

```bash
open3d-four-view \
  --input_path input.pcd \
  --output_path output.png \
  --overlay-json '{"car_model_id":"CAR001","branch":"main","commit":"abc123","soc":"soc2"}' \
  --color-legend-json '{"at128p_front":{"rgb":[255,0,0]}}'
```

`--coverage` defaults to `1.0`, meaning full point-cloud range. Values must be from `0` to `1`.

## Rendering Backend Notes

Four-view rendering uses Open3D `OffscreenRenderer` with OpenGL/EGL graphics rendering. The `--gpu` flag asks Open3D to prefer GPU graphics rendering where the runtime supports it. It is intentionally not a CUDA tensor pipeline and does not run CUDA voxel/downsample operations.

When `--gpu` is used, the package removes known software-rendering environment variables such as `LIBGL_ALWAYS_SOFTWARE=true`, `OPEN3D_CPU_RENDERING`, and `MESA_LOADER_DRIVER_OVERRIDE=llvmpipe/softpipe` before importing Open3D. It keeps `EGL_PLATFORM=surfaceless` because that can be valid for headless EGL GPU rendering. If GPU rendering cannot be confirmed, a `RuntimeWarning` is emitted and rendering continues with the Open3D backend available in the current environment.

In current validation environments, Open3D 0.19.0 with CUDA 12.1 can use GPU rendering. On RTX 50 / Blackwell GPUs, avoid Open3D CUDA tensor point-cloud batch processing unless you are using a CUDA/Open3D build that explicitly supports Blackwell.

References:

- Open3D Tensor: https://www.open3d.org/docs/latest/tutorial/core/tensor.html
- Open3D CPU/Software Rendering: https://www.open3d.org/docs/latest/tutorial/visualization/cpu_rendering.html
- NVIDIA Blackwell Compatibility Guide: https://docs.nvidia.com/cuda/blackwell-compatibility-guide/
