phg-vis 5.0.0

A package for the PHG modeling language and 3D visualization tool.

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

pip install phg_vis

Install from source:

pip install .

Optional shader dependencies:

pip install .[shader]

Quick Start

Render a PHG script interactively:

from pathlib import Path
import phg

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

Render a deterministic PNG:

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:

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

[Paths]
rvmReader=
wlkxReader=
meshRoot=./

Notes:

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

phg/vis/vis.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

{
    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

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