Metadata-Version: 2.1
Name: phg_vis
Version: 5.0.3
Summary: A package for the PHG modeling language and 3D visualization tool.
Home-page: https://github.com/panguojun/Coordinate-System
Author: romeosoft
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 VIS

`phg_vis` is a Windows-oriented PHG modeling and visualization package. It bundles the Python API, the PHG runtime bridge, the desktop `vis.exe` viewer, Dragpad file opener, and required viewer runtime files.

Current release target: `5.0.3`

## What Is Included

- Python package `phg`
- Desktop viewer: `vis.exe`
- PHG geometry/runtime bridge: `GCU.dll`
- Drag-and-drop / double-click opener: `dragpad.exe`
- Runtime DLLs needed by the viewer
- PHG visualization helpers for interactive viewing, screenshots, web preview, and engineering scene inspection

The package is designed to be environment-neutral. Do not ship private machine paths, user profile paths, reader executable paths, or project-specific absolute directories in package defaults.

## Main Features

- Interactive PHG rendering through the bundled `vis.exe`
- PHG script execution through `GCU.dll`
- Direct loading of `.phg`, `.sce`, `.sm`, `.grid`, `.obj`, `.wlkx`, and `.rvm` where the corresponding reader is configured
- Unicode-safe file opening through Dragpad, including non-ASCII parent directories
- Remote VIS probe with local fallback
- Stable local cold-start behavior before sending PHG content to VIS
- PHG path-node syntax such as `a/b/c`
- Local-first node reference lookup for scoped PHG scripts
- Boolean-script workflow support through the PHG runtime
- Diagnostic logs for PHG execution and viewer-side request handling
- Web/Three.js preview helpers for exported OBJ scenes
- Optional shader conversion and rendering helpers

## Installation

```bash
pip install phg_vis
```

Install from source:

```bash
pip install .
```

Optional extras:

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

## Quick Start

Interactive VIS render:

```python
from pathlib import Path
import phg

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

PNG render:

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

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

Inline script:

```python
import phg

script = """
{
  sample{
    md:cylinder 0.25 3;
    rgb:120,180,255;
  }
}
setup();
draw('/sample');
"""

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

## PHG Syntax Requirements

Use one anonymous root block:

```phg
{
  scene{
    part{md:cylinder 0.25 3;}
  }
}
setup();
draw('/scene/part');
```

Avoid putting a named node directly at file root:

```phg
scene{
  part{md:cylinder 0.25 3;}
}
setup();
draw('scene');
```

Use spaces for `md:` parameters and commas for vectors:

```phg
{
  part{
    md:cylinder 0.25 3;
    xyz:1,2,3;
  }
}
```

## Path Nodes

PHG supports path-style node names:

```phg
{
  a/b/c{
    md:sphere 0.2;
    xyz:0,0,0;
  }
}
setup();
draw('/a/b/c');
```

Rules:

- `a/b/c{...}` creates or reuses the parent-child chain `a -> b -> c`.
- `/a/b/c` is an absolute path from the PHG root.
- `a/b/c` without a leading slash is relative to the current scope.
- `/` is a path separator unless it starts `//` or `/* ... */`.
- Use ASCII path segments for portable scripts.
- Do not use disk paths as node names. Put disk paths in quoted property values or function arguments.

## Local-First Node References

Node references are resolved from the local scope first, then upward through parent scopes.

This allows independent parent nodes to reuse child names safely:

```phg
{
  A{
    a{md:cylinder 0.3 1.0;}
    b{md:box 0.6 0.6 0.6;}
    u{md:bool union a b;}
  }

  B{
    a{md:cylinder 0.3 1.0; xyz:2,0,0;}
    b{md:box 0.6 0.6 0.6; xyz:2,0,0;}
    d{md:bool diff a b;}
  }
}
setup();
draw('/A/u');
draw('/B/d');
```

In `A/u`, `a` and `b` resolve under `A`. In `B/d`, `a` and `b` resolve under `B`.

Use absolute paths for intentional cross-scope references:

```phg
{
  shared{
    cutter{md:cylinder 0.2 2.0;}
  }

  part{
    body{md:box 1 1 1;}
    cut{md:bool diff body /shared/cutter;}
  }
}
setup();
draw('/part/cut');
```

## Boolean Script Guidance

Boolean nodes should reference stable geometry nodes that already exist in the relevant scope.

Recommended abstract form:

```phg
result{md:bool <op> <left_node> <right_node>;}
```

Recommended operation names:

- `union` / `add`
- `diff` / `sub`
- `intersect` / `int`

For large scenes, group boolean operands under their owner node. Avoid a flat global namespace with many repeated names.

## Inline PHG Expressions

Node bodies may contain inline PHG execution blocks:

```phg
{
  part{
    (r = 0.25;)
    md:cylinder 0.25 1.0;
  }
}
setup();
draw('/part');
```

Guidance:

- Inline expressions execute in the current node scope.
- Keep expression blocks small.
- Do not put long-running procedural modeling algorithms in PHG expressions.
- Final normalized node properties should still be constants.

## VIS Viewer Behavior

The canonical viewer executable is:

```text
vis.exe
```

Do not depend on temporary names such as `vis_fixed.exe`.

Dragpad behavior:

1. Attempts the configured VIS host.
2. If the remote host is unavailable within the short probe window, switches to local mode.
3. Starts local `vis.exe` if needed.
4. Waits for local VIS startup before sending PHG content.
5. Reads files through Unicode-safe paths.

Default Dragpad configuration:

```ini
[Paths]
ServerPath=vis.exe
ScenePath=./dat

[Network]
IpAddress=127.0.0.1
```

## Configuration

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

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

Reader paths are blank by default. Configure them at deployment time.

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

```ini
AUTO_FOCUS=true
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=./
```

Blank `SCREENSHOT_PATH` uses the viewer runtime default.

## Diagnostics

Two diagnostic layers may be enabled in the bundled runtime.

VIS-side log:

```text
vis_phg_diagnostics.log
```

Typical phases:

```text
enter
doPHG_begin
doPHG_end
setup_mesh_begin
setup_mesh_end
focus_begin
focus_end
done
```

ScePHG/GCU-side log:

```text
scephg_diagnostics.log
```

Typical phases:

```text
doPHG_enter
lock_acquired
init_done
auto_clear_begin
auto_clear_end
runtime_state_clear
script_ready
dostring_begin
dostring_end
doPHG_leave
```

Build-time diagnostic switches:

```cpp
VIS_ENABLE_PHG_DIAGNOSTICS
SCEPHG_ENABLE_DIAGNOSTICS
```

Set them to `0` in a production build to compile the diagnostic functions as no-ops.

## Remote And Local Viewer Use

For a running VIS server:

```bash
curl -X POST http://127.0.0.1:5088/phg --data-binary @scene.phg
```

For scripted Python use, prefer:

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

## AI Bridge Configuration

The optional AI bridge does not ship with a machine-specific default path.

Configure it with:

```bash
set PHG_AI_ROOT=<path-to-ai-phg-root>
```

or pass `ai_root=` explicitly:

```python
phg.visualize(script, mode="web", ai=True, ai_root="path/to/ai/phg")
```

The optional natural-language service reads:

```bash
set PHG_NL_AI_PATH=<path-to-intelligent-modeling-ai-src>
```

If this variable is not set, the service falls back to its built-in simple parser path where available.

## Regression PHG Scripts

Use these minimal scripts after runtime updates.

Basic:

```phg
{
  a{
    md:sphere 0.2;
    xyz:0,0,0;
  }
}
setup();
draw('/a');
```

Path node:

```phg
{
  a/b/c{
    md:sphere 0.2;
    xyz:0,0,0;
  }
}
setup();
draw('/a/b/c');
```

Path-node parse only:

```phg
{
  a/b/c{
    md:sphere 0.2;
    xyz:0,0,0;
  }
};
```

Expected result:

```text
VIS stays responsive.
VIS diagnostics reach done.
ScePHG diagnostics reach doPHG_leave.
```

## Packaging Rules

- Package `vis.exe`, `GCU.dll`, `dragpad.exe`, and required runtime DLLs together.
- Do not package local log files as release evidence.
- Do not package user-specific paths.
- Use environment variables for optional external tools.
- Keep `setup.py` version and `phg.__version__` synchronized.

## License

MIT
