Metadata-Version: 2.1
Name: phg_vis
Version: 5.0.2
Summary: A package for the PHG modeling language and 3D visualization tool.
Home-page: https://github.com/panguojun/Coordinate-System
Author: romeosoft
Author-email: 18858146@qq.com
Platform: Windows
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: process
Requires-Dist: psutil<7.0,>=5.9; extra == "process"
Provides-Extra: shader
Requires-Dist: numpy; extra == "shader"
Requires-Dist: pygame; extra == "shader"
Requires-Dist: PyOpenGL; extra == "shader"

# PHG

PHG is a Windows-oriented 3D modeling and visualization library built around a compact scene description language and a desktop viewer (`VIS`). It is designed for procedural geometry generation, engineering visualization, scene inspection, and pipe-system debugging workflows.

Current release target: `5.0.0`

## Core Capabilities

- Minimal PHG script language for hierarchical 3D scene generation
- Python APIs for interactive visualization and off-screen rendering
- Desktop viewer (`VIS`) for local inspection and scene debugging
- Reader-based scene loading for `.wlkx` and `.rvm`
- Direct loading for `.phg`, `.sce`, `.obj`, `.sm`, and `.grid`
- Screenshot export and interactive MP4 recording
- Pipe visualization helpers for world/local coordinate workflows

## Installation

```bash
pip install phg_vis
```

Install from source:

```bash
pip install .
```

Optional shader dependencies:

```bash
pip install .[shader]
```

## Quick Start

Render a PHG script interactively:

```python
from pathlib import Path
import phg

script = Path("scene.phg").read_text(encoding="utf-8")
phg.visualize(script, mode="vis")
```

Render a deterministic PNG:

```python
from pathlib import Path
from phg.visphg import image

script = Path("scene.phg").read_text(encoding="utf-8")
image(script, "scene.png")
```

Render inline content directly:

```python
import phg

script = """
{
    sample{md:cylinder 0.25 3; rgb:120,180,255;}
}setup_draw(sample);
"""

phg.visualize(script, mode="vis")
```

## VIS Viewer

`VIS` is the desktop front-end bundled with PHG. It is intended for local review, debugging, and scene inspection.

### Supported Inputs

- `.phg`
- `.sce`
- `.wlkx`
- `.rvm`
- `.obj`
- `.sm`
- `.grid`

### Current Interaction Features

- Auto-focus after loading or drag-dropping supported files
- Focus prefers actual loaded submesh bounds when available
- `Tab` cycles scene observation targets instead of blindly walking every object
- If the camera is far away from the next observation target, VIS automatically pulls in to a practical viewing distance
- `Shot` exports a PNG screenshot
- `REC / STOP` records viewport video
- `R` toggles recording
- Recording output is MP4 only
- Temporary PNG frames are used internally during recording and are deleted after successful encoding
- If MP4 encoding fails, the temporary frame directory is kept for troubleshooting
- Camera clip planes are initialized from scene scale and remain stable during wheel zooming

### Recording Requirements

Recording requires `ffmpeg.exe` to be available in `PATH`.

Behavior:

1. Press `REC` or `R` to start recording.
2. Frames are captured into a temporary directory.
3. Press `STOP` or `R` again to finish.
4. VIS encodes the recording to MP4 automatically.
5. On success, temporary frames are removed.
6. On failure, VIS keeps the frame directory and reports it in the notification.

## Default Configuration

Do not ship machine-specific absolute paths in the library package. Use environment-neutral defaults and fill in reader paths during deployment.

### `phg/vis/config.ini`

```ini
[Paths]
rvmReader=
wlkxReader=
meshRoot=./
```

Notes:

- `rvmReader` and `wlkxReader` are intentionally blank by default.
- `meshRoot=./` keeps the package environment-neutral.

### `phg/vis/vis.ini`

```ini
AUTO_FOCUS=true
CAMERA=
CONSOLE=true
COORD_HAND=LH
COORD_MIRROR_Z=false
COORD_UP=YUP
ENABLE_DUAL_SCREEN=false
HOSTIP=127.0.0.1
LAST_MESH_PATH=./
RECORD_FPS=12
SCREENSHOT_PATH=
meshRoot=./
```

Notes:

- Blank `SCREENSHOT_PATH` falls back to the desktop at runtime.
- `AUTO_FOCUS=true` is the recommended default.
- `RECORD_FPS=12` is the current balanced default for interactive recording.

## Recommended Workflow

For engineering or automatic-piping tasks, prefer this inspection order:

1. Intermediate debug PHG
2. Final geometry PHG
3. Deterministic PNG snapshot
4. Interactive VIS review when manual inspection is needed

This helps separate semantic-path problems, pose-layer problems, and final geometry translation problems.

## Troubleshooting

### Scene loads but nothing is visible

Check:

1. The input file was actually loaded.
2. Auto-focus is enabled.
3. The scene contains valid submeshes.
4. The camera is not still parked on the previous scene.

### `.wlkx` or `.rvm` cannot be opened

Check:

1. Reader executables are configured in `config.ini`.
2. The reader can produce the expected `.sce` and mesh database outputs.
3. The output directory is writable.

### Recording fails

Check:

1. `ffmpeg.exe` is available in `PATH`.
2. The output location is writable.
3. The notification reports a temporary frame directory for inspection.

## Minimal Syntax Reminder

```phg
{
    part{
        md:cylinder 5 20;
        rgb:180,180,220;
    }
}setup_draw(part);
```

Rules:

- Use root braces `{ ... }`
- Finish with `setup(); draw();` or `setup_draw(...)`
- Use spaces for `md:` arguments
- Use commas for vector values such as `xyz:1,2,3`

## Python API Snapshot

```python
import phg

phg.visualize("box(10);", mode="vis")
phg.image("sphere(5);", filename="sphere.png")
phg.visualize("box(10);", mode="web", out_html="view.html")
```

## Versioning

This release line is prepared as `5.0.0` because VIS behavior changed materially in user-facing areas:

- scene auto-focus after load
- observation-target camera cycling
- MP4 recording workflow
- stabilized clip-plane behavior
- release-oriented default configuration cleanup

## License

MIT
