Skip to content

Commit b489240

Browse files
bnbailey-pslbnbailey-psl
committed
[v0.0.3] 2025-08-23
## Context - Added comprehensive file loading support with `loadPLY()`, `loadOBJ()`, and `loadXML()` methods - Enhanced `loadPLY()` with 5 overloads supporting origin, height, rotation, color, and upaxis transformations - Enhanced `loadOBJ()` with 4 overloads including scale transformations and upaxis specification - Added complete `loadXML()` implementation for Helios XML geometry files - Extended native C++ wrapper with 9 new file loading functions and proper error handling - Added comprehensive parameter validation and security path checking - Implemented `addTriangleTextured()` - Implemented `addTrianglesFromArraysTextured()` ## Examples - Added example geometry files: `suzanne.ply`, `suzanne.obj`, `suzanne.mtl`, and `leaf_cube.xml` - Updated `external_geometry_sample.py` and `stanford_bunny_radiation.py` for demonstration ## Documentation - Major README.md restructuring with simplified installation and quick start guide - Streamlined documentation structure with consolidated user guide sections - Updated Doxygen configuration for cleaner documentation generation - Removed redundant documentation files and consolidated content ## Testing - Enhanced existing tests with file loading functionality validation - Added cross-platform API tests that work with and without native library
1 parent 4fb99ec commit b489240

46 files changed

Lines changed: 259558 additions & 4447 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/pytest-linux-gpu.yaml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
name: PyHelios GPU Tests on Linux EC2
2+
3+
on:
4+
push:
5+
branches: [ "master" ]
6+
7+
env:
8+
BUILD_TYPE: Release
9+
10+
permissions:
11+
id-token: write
12+
contents: read
13+
14+
jobs:
15+
16+
start-gpu:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- uses: aws-actions/configure-aws-credentials@v2
20+
with:
21+
role-to-assume: ${{ secrets.OIDC_ROLE_ARN }}
22+
aws-region: us-west-2
23+
- run: |
24+
aws ec2 start-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
25+
aws ec2 wait instance-running --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
26+
27+
run_pyhelios_gpu_tests:
28+
runs-on: [self-hosted]
29+
needs: start-gpu
30+
steps:
31+
- uses: actions/checkout@v3
32+
with:
33+
submodules: 'recursive'
34+
35+
- name: Set up Python
36+
uses: actions/setup-python@v4
37+
with:
38+
python-version: '3.9'
39+
40+
- name: Install PyHelios and dependencies
41+
run: |
42+
python -m pip install --upgrade pip
43+
pip install -e .[dev]
44+
45+
- name: Build PyHelios with all plugins (GPU included)
46+
run: |
47+
# Build with all available plugins including GPU-accelerated ones
48+
./build_scripts/build_helios --clean --plugins radiation,visualizer,weberpenntree
49+
50+
- name: Check plugin status
51+
run: |
52+
python -m pyhelios.plugins status
53+
python -c "from pyhelios.plugins import print_plugin_status; print_plugin_status()"
54+
55+
- name: Run PyHelios GPU tests
56+
run: |
57+
# Run native-only tests that require GPU plugins
58+
if ! pytest -v -m "native_only" --tb=short --log-file=pyhelios_gpu_tests.log; then
59+
echo "==== PyHelios GPU tests failed; dumping pyhelios_gpu_tests.log ===="
60+
cat pyhelios_gpu_tests.log
61+
exit 1
62+
fi
63+
64+
- name: Run comprehensive test suite
65+
run: |
66+
# Run full test suite to ensure nothing is broken
67+
if ! pytest -v --tb=short --log-file=pyhelios_full_tests.log; then
68+
echo "==== PyHelios comprehensive tests failed; dumping pyhelios_full_tests.log ===="
69+
cat pyhelios_full_tests.log
70+
exit 1
71+
fi
72+
73+
- name: Upload test logs
74+
uses: actions/upload-artifact@v3
75+
if: always()
76+
with:
77+
name: pyhelios-gpu-test-logs
78+
path: |
79+
pyhelios_gpu_tests.log
80+
pyhelios_full_tests.log
81+
build_scripts/build.log
82+
83+
stop-gpu:
84+
needs: run_pyhelios_gpu_tests
85+
if: always()
86+
runs-on: ubuntu-latest
87+
steps:
88+
- uses: aws-actions/configure-aws-credentials@v2
89+
with:
90+
role-to-assume: ${{ secrets.OIDC_ROLE_ARN }}
91+
aws-region: us-west-2
92+
- run: |
93+
aws ec2 stop-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
94+
aws ec2 wait instance-stopped --instance-ids ${{ secrets.EC2_INSTANCE_ID }}

‎README.md‎

Lines changed: 42 additions & 173 deletions
Original file line numberDiff line numberDiff line change
@@ -12,224 +12,93 @@ Cross-platform Python bindings for [Helios](https://github.com/PlantSimulationLa
1212

1313
PyHelios provides a Python interface to the powerful Helios C++ library for 3D physical simulation of plant and environmental systems. It enables plant modeling, geometry manipulation, and biophysical simulations including GPU-accelerated radiation transfer, photosynthesis, and plant architecture modeling.
1414

15-
For complete documentation of PyHelios, please visit: https://plantsimulationlab.github.io/PyHelios/
15+
📖 **[Complete Documentation](https://plantsimulationlab.github.io/PyHelios/)**
1616

17-
**Important**
18-
This project is in the early stages of development. The Python API only has a limited subset of the Helios C++ functionality.
19-
The code is likely to change quickly, with backward compatability not being maintained. It is recommended when you update your code to read the changelog in `docs/CHANGELOG.md`.
17+
## Quick Start
2018

21-
For complete documentation of the Helios C++ library, please visit https://baileylab.ucdavis.edu/software/helios
19+
### Installation
2220

23-
## Platform Support
24-
25-
PyHelios now works across multiple platforms:
26-
27-
- ✅ **Windows** (x64) - Full native support
28-
- ✅ **macOS** (Intel/Apple Silicon) - Native support with build-from-source
29-
- ✅ **Linux** (x64) - Native support with build-from-source
30-
- ✅ **Development Mode** - Explicit mock mode for development without native libraries
31-
32-
## Installation
33-
34-
### Full Installation with Native Helios Libraries
35-
36-
#### Windows
37-
```bash
38-
# Prerequisites: Visual Studio 2019+ or Build Tools
39-
40-
# Clone the Helios git repository
41-
git clone --recursive git@github.com:PlantSimulationLab/PyHelios.git
42-
cd PyHelios/
43-
44-
# Build native Helios C++ library
45-
./build_scripts/build_helios
46-
47-
# Install Python dependencies
48-
pip install -e .
49-
```
50-
51-
#### macOS
52-
```bash
53-
# Clone the Helios git repository
54-
git clone --recursive git@github.com:PlantSimulationLab/PyHelios.git
55-
cd PyHelios/
56-
57-
# Install Helios C++ dependencies
58-
source helios-core/utilities/dependencies.sh
59-
60-
# Build native Helios C++ library
61-
./build_scripts/build_helios
62-
63-
# Install Python dependencies
64-
pip install -e .
65-
```
66-
67-
#### Linux (Ubuntu/Debian)
6821
```bash
69-
# Clone the Helios git repository
70-
git clone --recursive git@github.com:PlantSimulationLab/PyHelios.git
22+
# Clone repository
23+
git clone --recursive https://github.com/PlantSimulationLab/PyHelios.git
7124
cd PyHelios/
7225

73-
# Install Helios C++ dependencies
74-
source helios-core/utilities/dependencies.sh
75-
76-
# Build native Helios C++ library
26+
# Build native libraries (platform-specific instructions in docs)
7727
./build_scripts/build_helios
7828

79-
# Install Python dependencies
29+
# Install PyHelios
8030
pip install -e .
8131
```
8232

83-
## Usage
33+
**Platform Support:** Windows, macOS, Linux, and development mode for any platform.
8434

85-
- Creating a basic Context and adding a Patch
35+
### First Example
8636

8737
```python
8838
from pyhelios import Context
8939
from pyhelios.types import *
9040

41+
# Create simulation context
9142
context = Context()
9243

44+
# Add a patch primitive
9345
center = vec3(2, 3, 4)
9446
size = vec2(1, 1)
9547
color = RGBcolor(0.25, 0.25, 0.25)
96-
9748
patch_uuid = context.addPatch(center=center, size=size, color=color)
49+
50+
print(f"Created patch: {patch_uuid}")
9851
```
9952

100-
- Creating a Lemon tree and an Olive tree using WeberPennTree plugin
53+
### Tree Modeling
10154

10255
```python
10356
from pyhelios import Context, WeberPennTree
10457

10558
context = Context()
10659
wpt = WeberPennTree(context)
10760

108-
tree_id_lemon = wpt.buildTree(wpt_type=WeberPennTree.WPTType.LEMON)
109-
tree_id_olive = wpt.buildTree(wpt_type=WeberPennTree.WPTType.OLIVE)
61+
# Generate procedural tree
62+
tree_id = wpt.buildTree(WeberPennTree.WPTType.LEMON)
11063
```
11164

112-
- GPU-accelerated radiation simulation with graceful plugin handling
65+
## Documentation
11366

114-
```python
115-
from pyhelios import Context, RadiationModel
67+
| Section | Description |
68+
|---------|-------------|
69+
| **[Getting Started](https://plantsimulationlab.github.io/PyHelios/getting_started.html)** | Installation, setup, and first steps |
70+
| **[User Guide](https://plantsimulationlab.github.io/PyHelios/user_guide.html)** | Core concepts, API reference, and examples |
71+
| **[Cross-Platform](https://plantsimulationlab.github.io/PyHelios/cross_platform.html)** | Platform-specific usage and deployment |
72+
| **[Plugin System](https://plantsimulationlab.github.io/PyHelios/plugin_system.html)** | Available plugins and configuration |
11673

117-
context = Context()
74+
## Key Features
11875

119-
# Add geometry to the context here (PLY files, patches, trees, etc.)
120-
121-
with RadiationModel(context) as radiation:
122-
radiation.addRadiationBand(band_label="SW")
123-
radiation.setDirectRayCount(band_label="SW", ray_count=100)
124-
radiation.setDiffuseRayCount(band_label="SW", ray_count=1000)
125-
126-
# Run GPU simulation
127-
radiation.runBand(band_label="SW")
128-
results = radiation.getTotalAbsorbedFlux()
129-
130-
# Apply native pseudocolor mapping for visualization
131-
all_uuids = context.getAllUUIDs()
132-
context.colorPrimitiveByDataPseudocolor(all_uuids, "radiation_flux_SW", "hot", 256)
133-
```
76+
- **Cross-platform**: Windows, macOS, and Linux support
77+
- **Plant modeling**: WeberPennTree procedural generation
78+
- **GPU acceleration**: OptiX-powered radiation simulation
79+
- **3D visualization**: OpenGL-based real-time rendering
80+
- **Flexible plugins**: 21 available plugins for specialized tasks
81+
- **Development mode**: Mock mode for development without native libraries
13482

135-
### Command-Line Plugin Tools
83+
## Quick Commands
13684

13785
```bash
138-
# Comprehensive plugin status
139-
python -m pyhelios.plugins status
140-
141-
# System analysis and recommendations
142-
python -m pyhelios.plugins discover
143-
144-
# Information about specific plugins
145-
python -m pyhelios.plugins info radiation
146-
147-
# Validate plugin combinations
148-
python -m pyhelios.plugins validate --plugins radiation,visualizer
149-
```
150-
151-
## Development and Testing
152-
153-
```bash
154-
# Run tests (works on all platforms)
86+
# Test installation
15587
pytest
15688

157-
# Run only cross-platform tests
158-
pytest -m cross_platform
159-
160-
# Run only tests that need native libraries
161-
pytest -m native_only
162-
163-
# Run with coverage
164-
pytest --cov=pyhelios
165-
```
166-
167-
## Building Native Libraries
168-
169-
PyHelios now supports **flexible plugin selection** for customized builds based on your hardware and requirements. Choose from **21 available plugins** using predefined profiles or explicit selection.
170-
171-
### Advanced Plugin Selection
172-
173-
```bash
174-
# Custom plugin selection
175-
build_scripts/build_helios --plugins weberpenntree,visualizer
176-
177-
# Interactive selection (guided setup)
178-
build_scripts/build_helios --interactive
179-
180-
# Exclude problematic plugins
181-
build_scripts/build_helios --exclude radiation
182-
```
183-
184-
### Configuration File Support
185-
186-
Create `pyhelios_config.yaml` for persistent plugin preferences:
89+
# Check plugin status
90+
python -m pyhelios.plugins status
18791

188-
```yaml
189-
plugins:
190-
selection_mode: "profile"
191-
profile: "standard"
192-
excluded_plugins:
193-
- radiation # Exclude if no GPU available
92+
# Interactive plugin selection
93+
./build_scripts/build_helios --interactive
19494
```
19595

196-
### Available Plugin Profiles
197-
198-
- **minimal**: Core functionality (weberpenntree, canopygenerator, solarposition)
199-
- **standard**: Standard features with visualization (adds energybalance, photosynthesis, visualizer)
200-
- **gpu-accelerated**: High-performance GPU features (adds radiation for ray tracing)
201-
- **research**: Comprehensive research suite (most plugins for academic use)
202-
- **production**: Production-ready features (reliable, well-tested plugins)
203-
- **visualization**: Focus on rendering and visualization
204-
- **sensing**: Remote sensing and LiDAR simulation
205-
- **physics**: Comprehensive physics modeling
206-
- **development**: Minimal set for PyHelios development
207-
208-
## Troubleshooting
209-
210-
### Import Errors
211-
- Verify installation: `pip list | grep pyhelios`
212-
- Check Python version: Requires Python 3.7+
213-
- Try reinstalling: `pip install -e . --force-reinstall`
214-
215-
## Advanced Features
216-
217-
### GPU Radiation Simulation
218-
- OptiX-accelerated ray tracing for realistic radiation modeling
219-
- Direct and diffuse radiation calculations
220-
- Multi-bounce scattering simulation
221-
- Native pseudocolor mapping for visualization
222-
- Example: `docs/examples/stanford_bunny_radiation.py`
223-
224-
### C++ Plugin Development
225-
For developers looking to integrate additional C++ plugins, see `docs/cpp_plugin_integration_guide.md` for comprehensive guidance on:
226-
- Native library building and linking
227-
- Python wrapper implementation
228-
- Cross-platform considerations
229-
- Testing and documentation standards
230-
231-
For additional support, see the [Helios documentation](https://baileylab.ucdavis.edu/software/helios) or [GitHub issues](https://github.com/PlantSimulationLab/PyHelios/issues).
232-
96+
## Support
23397

98+
- **Documentation**: https://plantsimulationlab.github.io/PyHelios/
99+
- **Issues**: [GitHub Issues](https://github.com/PlantSimulationLab/PyHelios/issues)
100+
- **Helios C++ Docs**: https://baileylab.ucdavis.edu/software/helios
234101

102+
---
235103

104+
**Note**: This project is in active development. The API may change quickly - see `docs/CHANGELOG.md` for updates.

‎docs/CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,31 @@
11
# Changelog
22

3+
# [v0.0.3] 2025-08-23
4+
5+
## Context
6+
- Added comprehensive file loading support with `loadPLY()`, `loadOBJ()`, and `loadXML()` methods
7+
- Enhanced `loadPLY()` with 5 overloads supporting origin, height, rotation, color, and upaxis transformations
8+
- Enhanced `loadOBJ()` with 4 overloads including scale transformations and upaxis specification
9+
- Added complete `loadXML()` implementation for Helios XML geometry files
10+
- Extended native C++ wrapper with 9 new file loading functions and proper error handling
11+
- Added comprehensive parameter validation and security path checking
12+
- Implemented `addTriangleTextured()`
13+
- Implemented `addTrianglesFromArraysTextured()`
14+
15+
## Examples
16+
- Added example geometry files: `suzanne.ply`, `suzanne.obj`, `suzanne.mtl`, and `leaf_cube.xml`
17+
- Updated `external_geometry_sample.py` and `stanford_bunny_radiation.py` for demonstration
18+
19+
## Documentation
20+
- Major README.md restructuring with simplified installation and quick start guide
21+
- Streamlined documentation structure with consolidated user guide sections
22+
- Updated Doxygen configuration for cleaner documentation generation
23+
- Removed redundant documentation files and consolidated content
24+
25+
## Testing
26+
- Enhanced existing tests with file loading functionality validation
27+
- Added cross-platform API tests that work with and without native library
28+
329
# [v0.0.2] 2025-08-22
430

531
## Context

0 commit comments

Comments
 (0)