phg-vis 5.0.3

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

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

pip install phg_vis

Install from source:

pip install .

Optional extras:

pip install .[shader]
pip install .[process]

Quick Start

Interactive VIS render:

from pathlib import Path
import phg

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

PNG render:

from pathlib import Path
from phg.visphg import image

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

Inline script:

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:

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

Avoid putting a named node directly at file root:

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

Use spaces for md: parameters and commas for vectors:

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

Path Nodes

PHG supports path-style node names:

{
  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:

{
  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:

{
  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:

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:

{
  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:

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:

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

[Network]
IpAddress=127.0.0.1

Configuration

phg/vis/config.ini

[Paths]
rvmReader=
wlkxReader=
meshRoot=./

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

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

vis_phg_diagnostics.log

Typical phases:

enter
doPHG_begin
doPHG_end
setup_mesh_begin
setup_mesh_end
focus_begin
focus_end
done

ScePHG/GCU-side log:

scephg_diagnostics.log

Typical phases:

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:

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:

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

For scripted Python use, prefer:

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:

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

or pass ai_root= explicitly:

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

The optional natural-language service reads:

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:

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

Path node:

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

Path-node parse only:

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

Expected result:

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