phg-vis 1.3.0__tar.gz → 1.3.2__tar.gz

{phg_vis-1.3.0/phg_vis.egg-info → phg_vis-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: phg_vis
-Version: 1.3.0
+Version: 1.3.2
 Summary: A package for the PHG modeling language and 3D visualization tool.
 Home-page: https://github.com/panguojun/Coordinate-System
 Author: romeosoft
@@ -13,20 +13,21 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-# PHG - Minimalist 3D Modeling Language
+# PHG - Python Hypergraphics Library
 
-PHG (Bacteriophage) is a specialized modeling language for describing 3D scene node trees. Combining concepts from group theory, it provides custom overloading capabilities for variables and operations, making it particularly suitable for describing complex 3D scenes and 2D sprite structures.
+PHG (Python Hypergraphics) is a powerful 3D modeling and visualization library that combines a minimalist modeling language with Python integration. It provides procedural 3D scene generation, shader-based rendering, and specialized pipe system visualization.
 
 ---
 
 ## 🌟 Features
 
-- **Minimalist Syntax** - Declarative node tree description
+- **Minimalist Syntax** - Declarative node tree description for 3D scenes
 - **Hierarchical Modeling** - Support for nested nodes and transform inheritance
 - **Parametric Design** - Flexible property system and function definitions
-- **Topological Structures** - Two organization methods: sequence and array composition
-- **Visualization Rendering** - Powerful offscreen rendering and screenshot capabilities
-- **Python Integration** - Convenient Python API
+- **Pipe Visualization** - Specialized system for visualizing pipe structures with world/local coordinate support
+- **Shader Conversion** - Convert PHG scripts to GLSL shaders for GPU rendering
+- **Dual Rendering Modes** - Both real-time visualization (vis.exe) and offscreen rendering
+- **Python Integration** - Comprehensive Python API for all features
 
 ---
 
@@ -402,6 +403,122 @@ for size in [5, 10, 15, 20]:
 
 ---
 
+## 🔧 Pipe Visualization System
+
+PHG includes a specialized pipe visualization system for creating 3D pipe structures from simple string commands.
+
+### Pipe String Commands
+
+- **F** - Forward (move forward in current direction)
+- **B** - Back (move backward in current direction)
+- **R** - Right (turn right and move)
+- **L** - Left (turn left and move)
+- **U** - Up (turn up and move)
+- **D** - Down (turn down and move)
+
+### World Coordinate System
+
+World coordinate pipes use absolute directions regardless of current orientation:
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+# Create a pipe in world coordinates
+# F moves along world Z+, R moves along world X+, etc.
+start_pos = coord3(vec3(0, 0, 0), quat(1, 0, 0, 0))
+phg_script = phg.world_pipestr_vis("FFRRUD", start_pos)
+
+# Custom pipe appearance
+phg.world_pipestr_vis(
+    "FFLLUU",
+    start_pos,
+    pipe_color=(255, 100, 50),  # Orange pipe
+    pipe_radius=0.5               # Thicker pipe
+)
+```
+
+### Local Coordinate System
+
+Local coordinate pipes use directions relative to current orientation:
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+# Create a pipe in local coordinates
+# F moves forward relative to current orientation
+start_pos = coord3(vec3(0, 0, 0), quat(1, 0, 0, 0))
+phg_script = phg.local_pipestr_vis("FFRRUD", start_pos)
+
+# The same string produces different results in local vs world coordinates
+phg.local_pipestr_vis(
+    "FFRRFF",  # Forward, Forward, Right turn, Right turn, Forward, Forward
+    start_pos,
+    pipe_color=(0, 255, 100)  # Green pipe
+)
+```
+
+### Direct PHG Script Generation
+
+For advanced use cases, you can generate PHG scripts without immediate visualization:
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+start = coord3(vec3(5, 0, 0), quat(1, 0, 0, 0))
+
+# Generate PHG script for world coordinates
+world_phg = phg.world_pipe_to_phg("FFRUD", start)
+
+# Generate PHG script for local coordinates
+local_phg = phg.local_pipe_to_phg("FFRUD", start)
+
+# Visualize later
+phg.vis(world_phg)
+```
+
+### Example: Complex Pipe System
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+# Create a complex pipe network
+def create_pipe_network():
+    # Main pipeline
+    main_pipe = phg.world_pipestr_vis(
+        "FFFFRRFFRRUUFFLLFF",
+        coord3(vec3(0, 0, 0), quat(1, 0, 0, 0)),
+        pipe_color=(100, 100, 255),
+        pipe_radius=0.5
+    )
+
+    # Branch 1
+    branch1 = phg.world_pipestr_vis(
+        "RRUUFFFF",
+        coord3(vec3(4, 0, 0), quat(1, 0, 0, 0)),
+        pipe_color=(255, 100, 100),
+        pipe_radius=0.3
+    )
+
+    # Branch 2
+    branch2 = phg.local_pipestr_vis(
+        "FFLLDDFF",
+        coord3(vec3(8, 2, 2), quat(1, 0, 0, 0)),
+        pipe_color=(100, 255, 100),
+        pipe_radius=0.3
+    )
+
+    return main_pipe, branch1, branch2
+
+# Create and visualize the network
+pipes = create_pipe_network()
+```
+
+---
+
 ## 💡 Complete Examples
 
 ### Example 1: Simple Geometry
@@ -581,7 +698,6 @@ Recommended maximum resolution is **4096 x 4096**. Excessively large resolutions
 ## 🔗 Links
 
 - [PyPI Package](https://pypi.org/project/phg/)
-- [Official Documentation](https://your.documentation.link)
 - [Mathematical Foundation](https://github.com/panguojun/Coordinate-System)
 
 ---

{phg_vis-1.3.0 → phg_vis-1.3.2}/README.md

@@ -1,17 +1,18 @@
-# PHG - Minimalist 3D Modeling Language
+# PHG - Python Hypergraphics Library
 
-PHG (Bacteriophage) is a specialized modeling language for describing 3D scene node trees. Combining concepts from group theory, it provides custom overloading capabilities for variables and operations, making it particularly suitable for describing complex 3D scenes and 2D sprite structures.
+PHG (Python Hypergraphics) is a powerful 3D modeling and visualization library that combines a minimalist modeling language with Python integration. It provides procedural 3D scene generation, shader-based rendering, and specialized pipe system visualization.
 
 ---
 
 ## 🌟 Features
 
-- **Minimalist Syntax** - Declarative node tree description
+- **Minimalist Syntax** - Declarative node tree description for 3D scenes
 - **Hierarchical Modeling** - Support for nested nodes and transform inheritance
 - **Parametric Design** - Flexible property system and function definitions
-- **Topological Structures** - Two organization methods: sequence and array composition
-- **Visualization Rendering** - Powerful offscreen rendering and screenshot capabilities
-- **Python Integration** - Convenient Python API
+- **Pipe Visualization** - Specialized system for visualizing pipe structures with world/local coordinate support
+- **Shader Conversion** - Convert PHG scripts to GLSL shaders for GPU rendering
+- **Dual Rendering Modes** - Both real-time visualization (vis.exe) and offscreen rendering
+- **Python Integration** - Comprehensive Python API for all features
 
 ---
 
@@ -387,6 +388,122 @@ for size in [5, 10, 15, 20]:
 
 ---
 
+## 🔧 Pipe Visualization System
+
+PHG includes a specialized pipe visualization system for creating 3D pipe structures from simple string commands.
+
+### Pipe String Commands
+
+- **F** - Forward (move forward in current direction)
+- **B** - Back (move backward in current direction)
+- **R** - Right (turn right and move)
+- **L** - Left (turn left and move)
+- **U** - Up (turn up and move)
+- **D** - Down (turn down and move)
+
+### World Coordinate System
+
+World coordinate pipes use absolute directions regardless of current orientation:
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+# Create a pipe in world coordinates
+# F moves along world Z+, R moves along world X+, etc.
+start_pos = coord3(vec3(0, 0, 0), quat(1, 0, 0, 0))
+phg_script = phg.world_pipestr_vis("FFRRUD", start_pos)
+
+# Custom pipe appearance
+phg.world_pipestr_vis(
+    "FFLLUU",
+    start_pos,
+    pipe_color=(255, 100, 50),  # Orange pipe
+    pipe_radius=0.5               # Thicker pipe
+)
+```
+
+### Local Coordinate System
+
+Local coordinate pipes use directions relative to current orientation:
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+# Create a pipe in local coordinates
+# F moves forward relative to current orientation
+start_pos = coord3(vec3(0, 0, 0), quat(1, 0, 0, 0))
+phg_script = phg.local_pipestr_vis("FFRRUD", start_pos)
+
+# The same string produces different results in local vs world coordinates
+phg.local_pipestr_vis(
+    "FFRRFF",  # Forward, Forward, Right turn, Right turn, Forward, Forward
+    start_pos,
+    pipe_color=(0, 255, 100)  # Green pipe
+)
+```
+
+### Direct PHG Script Generation
+
+For advanced use cases, you can generate PHG scripts without immediate visualization:
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+start = coord3(vec3(5, 0, 0), quat(1, 0, 0, 0))
+
+# Generate PHG script for world coordinates
+world_phg = phg.world_pipe_to_phg("FFRUD", start)
+
+# Generate PHG script for local coordinates
+local_phg = phg.local_pipe_to_phg("FFRUD", start)
+
+# Visualize later
+phg.vis(world_phg)
+```
+
+### Example: Complex Pipe System
+
+```python
+import phg
+from coordinate_system import vec3, quat, coord3
+
+# Create a complex pipe network
+def create_pipe_network():
+    # Main pipeline
+    main_pipe = phg.world_pipestr_vis(
+        "FFFFRRFFRRUUFFLLFF",
+        coord3(vec3(0, 0, 0), quat(1, 0, 0, 0)),
+        pipe_color=(100, 100, 255),
+        pipe_radius=0.5
+    )
+
+    # Branch 1
+    branch1 = phg.world_pipestr_vis(
+        "RRUUFFFF",
+        coord3(vec3(4, 0, 0), quat(1, 0, 0, 0)),
+        pipe_color=(255, 100, 100),
+        pipe_radius=0.3
+    )
+
+    # Branch 2
+    branch2 = phg.local_pipestr_vis(
+        "FFLLDDFF",
+        coord3(vec3(8, 2, 2), quat(1, 0, 0, 0)),
+        pipe_color=(100, 255, 100),
+        pipe_radius=0.3
+    )
+
+    return main_pipe, branch1, branch2
+
+# Create and visualize the network
+pipes = create_pipe_network()
+```
+
+---
+
 ## 💡 Complete Examples
 
 ### Example 1: Simple Geometry
@@ -566,7 +683,6 @@ Recommended maximum resolution is **4096 x 4096**. Excessively large resolutions
 ## 🔗 Links
 
 - [PyPI Package](https://pypi.org/project/phg/)
-- [Official Documentation](https://your.documentation.link)
 - [Mathematical Foundation](https://github.com/panguojun/Coordinate-System)
 
 ---

phg_vis-1.3.2/phg/__init__.py

@@ -0,0 +1,329 @@
+"""
+PHG - Python Hypergraphics Library
+===================================
+
+A powerful graphics library for procedural 3D visualization using PHG scripts.
+
+Main Features:
+- PHG script visualization via vis.exe
+- Shader-based rendering with GLSL conversion
+- Pipe system visualization with world/local coordinate systems
+- Multiple pipe visualization support
+- Real-time and image rendering capabilities
+
+Version: 1.3.1
+Author: PanGuoJun
+License: MIT
+"""
+
+from .visphg import vis, image
+from .shader_render import ShaderRenderer, render_shader
+from .phg_to_shader import PHGToShaderConverter, phg_to_shader
+from .pipe_string_phg import (
+    world_pipe_to_phg,
+    local_pipe_to_phg,
+    world_pipestr_vis,
+    local_pipestr_vis,
+    multiple_pipes_vis
+)
+
+# Extend ShaderRenderer class to support direct PHG rendering
+class PHGShaderRenderer(ShaderRenderer):
+    """Shader renderer that supports direct PHG rendering"""
+    
+    def render_phg(self, phg_script: str, duration=0, interactive=True):
+        """
+        Render PHG script
+        
+        Parameters:
+            phg_script: PHG script code
+            duration: Render duration
+            interactive: Whether to allow interaction
+            
+        Returns:
+            success: Whether rendering was successful
+        """
+        converter = PHGToShaderConverter()
+        shader_code = converter.generate_shader_code(phg_script)
+        
+        if not shader_code:
+            print("Error: PHG conversion failed")
+            return False
+            
+        return self.render_shader(shader_code, duration, interactive)
+
+# Convenience functions
+def render_phg(phg_script: str, width=800, height=600, duration=0, title="PHG Renderer"):
+    """
+    Directly render PHG script
+    
+    Parameters:
+        phg_script: PHG script code
+        width: Window width
+        height: Window height  
+        duration: Render duration
+        title: Window title
+    """
+    renderer = PHGShaderRenderer(width, height, title)
+    success = renderer.render_phg(phg_script, duration)
+    renderer.close()
+    return success
+
+def convert_phg_to_shader(phg_script: str) -> str:
+    """
+    Convert PHG script to GLSL shader code
+
+    Parameters:
+        phg_script: PHG script
+
+    Returns:
+        shader_code: GLSL shader code
+    """
+    return phg_to_shader(phg_script)
+
+def visualize_pipe_variants(pipe_variants, start_position=None, colors=None, coordinate_system='world'):
+    """
+    Visualize multiple pipe variants for comparison
+    
+    Parameters:
+        pipe_variants: List of pipe strings or configuration dictionaries
+        start_position: Starting coordinate (optional)
+        colors: List of colors for each pipe variant
+        coordinate_system: 'world' or 'local' coordinate system
+    
+    Returns:
+        PHG script string
+    """
+    from coordinate_system import vec3, quat, coord3
+    
+    # Handle start position
+    if start_position is None:
+        start_c = coord3(vec3(0, 0, 0), quat(1, 0, 0, 0))
+    else:
+        start_c = start_position
+    
+    # Handle different input formats
+    if isinstance(pipe_variants[0], str):
+        # Simple list of pipe strings
+        if colors is None:
+            # Generate distinct colors for each variant
+            import colorsys
+            colors = []
+            for i in range(len(pipe_variants)):
+                hue = i / len(pipe_variants)
+                rgb = colorsys.hsv_to_rgb(hue, 0.8, 0.9)
+                colors.append(tuple(int(c * 255) for c in rgb))
+        
+        if coordinate_system == 'world':
+            return world_pipestr_vis(pipe_variants, start_c, colors)
+        else:
+            return local_pipestr_vis(pipe_variants, start_c, colors)
+    
+    else:
+        # List of configuration dictionaries
+        pipe_configs = []
+        for i, variant in enumerate(pipe_variants):
+            if isinstance(variant, str):
+                config = {
+                    'pipe_str': variant,
+                    'start_c': start_c,
+                    'color': colors[i] if colors else None,
+                    'radius': 0.3
+                }
+            else:
+                config = variant
+                if 'start_c' not in config:
+                    config['start_c'] = start_c
+            
+            pipe_configs.append(config)
+        
+        return multiple_pipes_vis(pipe_configs, coordinate_system)
+
+def create_pipe_comparison_grid(pipe_strings, grid_size=(2, 2), start_position=None, 
+                               base_color=(0, 55, 255), coordinate_system='world'):
+    """
+    Create a grid layout for comparing multiple pipe paths
+    
+    Parameters:
+        pipe_strings: List of pipe strings to compare
+        grid_size: (rows, cols) for grid layout
+        start_position: Base starting position
+        base_color: Base color for pipes
+        coordinate_system: 'world' or 'local'
+    
+    Returns:
+        PHG script string
+    """
+    from coordinate_system import vec3, quat, coord3
+    
+    if start_position is None:
+        start_position = coord3(vec3(0, 0, 0), quat(1, 0, 0, 0))
+    
+    rows, cols = grid_size
+    spacing = 5.0  # Space between pipes in grid
+    
+    pipe_configs = []
+    
+    for i, pipe_str in enumerate(pipe_strings):
+        if i >= rows * cols:
+            break
+            
+        row = i // cols
+        col = i % cols
+        
+        # Calculate position in grid
+        x_offset = col * spacing
+        z_offset = row * spacing
+        
+        # Create individual start position for this pipe
+        individual_start = coord3(
+            vec3(
+                start_position.o.x + x_offset,
+                start_position.o.y,
+                start_position.o.z + z_offset
+            ),
+            start_position.Q()
+        )
+        
+        # Generate color variation
+        color_variation = (
+            min(255, base_color[0] + (i * 30) % 100),
+            min(255, base_color[1] + (i * 50) % 100),
+            min(255, base_color[2] + (i * 70) % 100)
+        )
+        
+        pipe_configs.append({
+            'pipe_str': pipe_str,
+            'start_c': individual_start,
+            'color': color_variation,
+            'radius': 0.25 + (i * 0.05)  # Vary radius slightly
+        })
+    
+    return multiple_pipes_vis(pipe_configs, coordinate_system)
+
+def generate_pipe_variants_from_rules(base_pipe, num_variants=5, apply_rules=None):
+    """
+    Generate pipe variants using transformation rules
+    
+    Parameters:
+        base_pipe: Base pipe string
+        num_variants: Number of variants to generate
+        apply_rules: List of rules to apply ('swap', 'insert', 'cancel')
+    
+    Returns:
+        List of pipe variant strings
+    """
+    if apply_rules is None:
+        apply_rules = ['swap', 'insert', 'cancel']
+    
+    variants = [base_pipe]
+    
+    # Import the pipe transformer if available
+    try:
+        from .pipe_string_phg import PipeStringTransformer
+        transformer = PipeStringTransformer()
+        
+        for _ in range(num_variants - 1):
+            current_pipe = base_pipe
+            
+            # Apply random transformations
+            import random
+            for _ in range(random.randint(1, 3)):
+                rule = random.choice(apply_rules)
+                
+                if rule == 'swap' and len(current_pipe) >= 2:
+                    i, j = random.sample(range(len(current_pipe)), 2)
+                    current_pipe = transformer.swap_positions(current_pipe, i, j)
+                
+                elif rule == 'insert':
+                    position = random.randint(0, len(current_pipe))
+                    direction = random.choice(list(transformer.CANCEL_PAIRS.keys()))
+                    current_pipe = transformer.insert_cancel_pair(current_pipe, position, direction)
+                
+                elif rule == 'cancel':
+                    current_pipe = transformer.cancel_adjacent_pairs(current_pipe)
+            
+            # Simplify and add if valid
+            simplified = transformer.simplify_path(current_pipe)
+            if simplified not in variants:
+                variants.append(simplified)
+    
+    except ImportError:
+        # Fallback: simple variant generation
+        import random
+        for i in range(num_variants - 1):
+            # Simple character shuffling
+            pipe_list = list(base_pipe)
+            random.shuffle(pipe_list)
+            variant = ''.join(pipe_list)
+            if variant not in variants:
+                variants.append(variant)
+    
+    return variants[:num_variants]
+
+# Enhanced pipe visualization with transformation support
+def visualize_pipe_with_transformations(pipe_string, start_position=None, 
+                                      transformations=None, show_variants=3):
+    """
+    Visualize a pipe string along with its transformed variants
+    
+    Parameters:
+        pipe_string: Base pipe string
+        start_position: Starting coordinate
+        transformations: List of transformation rules to apply
+        show_variants: Number of variants to show
+    
+    Returns:
+        PHG script string
+    """
+    # Generate variants
+    variants = generate_pipe_variants_from_rules(
+        pipe_string, 
+        num_variants=show_variants + 1,  # +1 for original
+        apply_rules=transformations
+    )
+    
+    # Create comparison visualization
+    return visualize_pipe_variants(variants, start_position)
+
+__all__ = [
+    # Core visualization functions
+    'vis',
+    'image',
+
+    # Shader rendering
+    'ShaderRenderer',
+    'render_shader',
+    'render_phg',
+    'PHGShaderRenderer',
+
+    # PHG conversion
+    'PHGToShaderConverter',
+    'phg_to_shader',
+    'convert_phg_to_shader',
+
+    # Pipe visualization
+    'world_pipe_to_phg',
+    'local_pipe_to_phg',
+    'world_pipestr_vis',
+    'local_pipestr_vis',
+    'multiple_pipes_vis',
+    
+    # Enhanced pipe visualization
+    'visualize_pipe_variants',
+    'create_pipe_comparison_grid',
+    'generate_pipe_variants_from_rules',
+    'visualize_pipe_with_transformations',
+]
+
+__version__ = "1.3.1"
+__author__ = "PanGuoJun"
+__description__ = "Python Hypergraphics Library"
+
+# Package initialization information
+print(f"PHG {__version__} - {__description__}")
+print("[OK] Visualization module loaded")
+print("[OK] Shader converter loaded") 
+print("[OK] Pipe visualization loaded")
+print("[OK] Multiple pipe visualization support loaded")
+print("[OK] Pipe transformation utilities loaded")