GAMA-Visualisation is a comprehensive real-time visualization package for GAMA Platform simulations with advanced performance monitoring, animation capabilities, and integrated simulation control.
This library enables researchers and developers to visualize GAMA agent-based simulations in real-time, providing powerful tools for monitoring performance, creating smooth animations, analyzing simulation behavior, and controlling simulation execution directly from Python.
pip install gama-visualisation- Python 3.8+ with required dependencies
- GAMA Platform (optional, for simulation control features): Install from gama-platform.org
# Optional: For GAMA simulation control
pip install gama-client
# Optional: For benchmarking and plotting features
pip install "gama-visualisation[benchmark]"import gama_visualisation
from gama_visualisation import SnapshotViewer
# Create real-time snapshot viewer
viewer = SnapshotViewer(
directory="path/to/simulation/snapshots",
image_prefix="frame_",
image_suffix=".png"
)
# Start real-time visualization
viewer.start()from gama_visualisation import SnapshotViewer, SimulationController
# Create viewer with integrated simulation control
viewer = SnapshotViewer("simulation_output/")
controller = SimulationController(
snapshot_viewer=viewer,
experiment_path="model.gaml",
experiment_name="main_experiment"
)
# Start viewer with simulation control (press SPACEBAR to start simulation)
viewer.start()from gama_visualisation.benchmarks import VisualizationBenchmark
# Create benchmark suite
benchmark = VisualizationBenchmark(
output_dir="benchmark_results",
enable_plotting=True
)
# Run comprehensive benchmarks
results = benchmark.run_full_benchmark_suite()
# Save results and generate plots
benchmark.save_results(results, format_type="json")For simulation control features, launch GAMA in server mode:
# Linux/MacOS
./gama-headless.sh -socket 6868
# Windows
gama-headless.bat -socket 6868gama-visualisation/
├── 📁 src/ # Main Python package source code
├── 📁 tests/ # Comprehensive test suite
├── 📁 examples/ # Complete examples and tutorials
├── 📁 Moving Example/ # Advanced animation demonstration
├── pyproject.toml # Python package configuration
├── LICENSE # Package license
└── pytest.ini # Testing configuration
| Example | Description | Documentation |
|---|---|---|
| Basic Example | Real-time snapshot visualization | 📖 Code |
| Simulation Control | Integrated GAMA simulation management | 📖 Code |
| Performance Analysis | Benchmarking and optimization tools | 📖 Code |
| Advanced Animation | Procedural animation with Bezier curves | 📖 Moving Example |
- Source Code Documentation: Technical documentation of the package structure
- Advanced Animation Example: Complete procedural animation tutorial
- Testing Guide: Comprehensive testing framework and best practices
Real-time image sequence viewer with automatic file monitoring:
- Watches directories for new simulation images
- Provides smooth scaling and performance optimization
- Displays real-time FPS and performance statistics
- Supports keyboard interaction and window management
Integrated GAMA simulation management:
- Connects to GAMA Platform server
- Controls experiment lifecycle (start/stop/step)
- Provides real-time status updates
- Integrates seamlessly with SnapshotViewer
Comprehensive system resource tracking:
- CPU usage and memory consumption monitoring
- Real-time FPS calculation and smoothing
- Performance statistics and trend analysis
- Configurable sampling rates and history retention
Professional performance analysis tools:
- Image processing performance benchmarks
- File monitoring efficiency tests
- Memory stress testing and leak detection
- Comparative analysis and reporting
git clone https://github.com/gama-platform/gama-visualisation.git
cd gama-visualisation
pip install -e src/# For GAMA simulation control
pip install gama-client
# For benchmarking with plots
pip install "gama-visualisation[benchmark]"
# For development tools
pip install "gama-visualisation[dev]"
# Install all optional dependencies
pip install "gama-visualisation[all]"# Run complete test suite
python -m pytest tests/
# Quick functionality test
python setup_package.py --quick-test
# Run benchmark suite
python examples/benchmark_example.py --full-suite
# Quick performance check
python examples/benchmark_example.py --quick-onlyGAMA_SERVER_HOST: GAMA server hostname (default: localhost)GAMA_SERVER_PORT: GAMA server port (default: 1001)GAMA_VIZ_CONFIG: Path to configuration file
Create gama_viz_config.json for persistent settings:
{
"viewer": {
"max_fps_samples": 20,
"throttle_delay": 0.05,
"auto_scale": true,
"show_fps": true
},
"performance": {
"max_cache_size": 200,
"enable_monitoring": true,
"log_performance": true
},
"ui": {
"window_width": 1200,
"window_height": 800,
"theme": "default",
"font_size": 11
}
}Expected performance on modern hardware:
- Image Processing: 100+ FPS for 1080p images
- File Monitoring: 1000+ files/second detection rate
- Memory Usage: <100MB for typical visualizations
- CPU Usage: <20% for real-time monitoring
- Real-time Visualization: Automatic directory monitoring with smooth image display
- Performance Monitoring: FPS tracking, memory usage, and system resource analysis
- Simulation Integration: Direct GAMA server communication and experiment control
- Advanced Processing: Image enhancement, filtering, and procedural animations
- Benchmarking Suite: Comprehensive performance analysis and optimization tools
- Professional Package: Modern Python structure with type hints and full testing
Contributions are welcome! Check the issues to see how you can help.
git clone https://github.com/gama-platform/gama-visualisation.git
cd gama-visualisation
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or
venv\\Scripts\\activate # Windows
# Install in development mode
pip install -e ".[dev]"- Follow PEP 8 style guidelines
- Add comprehensive tests for new features
- Update documentation for API changes
- Use type hints for all public functions
- Write clear commit messages
For more technical details and practical examples, check the documentation in the examples/ and src/ folders, or explore our comprehensive testing framework.