viva-safeland/viva_safeland

1. Overall shape

ViVa-SAFELAND is primarily a Python desktop simulation package for safe landing validation. The core runtime lives in the viva package, while docs/, tests/, and .github/workflows/ support documentation, verification, and release automation.

2. Primary entry points

The application startup path appears to run through viva/main.py and viva/launcher.py, which likely coordinate initialization, UI startup, and scenario selection. viva/__init__.py makes the package importable, and viva/viva_pegasus.py suggests an alternate integration entrypoint or platform-specific variant.

3. Runtime configuration boundary

viva/env.py is the central place for environment or configuration setup. In an architecture diagram, treat this as the boundary where runtime parameters, file paths, and execution settings are established before the rest of the app is launched.

4. User interface subsystem

viva/gui.py and the viva/GUI/ directory implement the desktop UI layer. The presence of forest-dark and forest-light themes indicates a themed Tk-style GUI rather than a web frontend. This layer is the operator-facing control surface for launching and controlling simulations.

5. Simulation and rendering subsystem

The core simulation logic is organized under viva/modules/:

- simulator.py for the simulation loop/state management

- render_drone.py for visual rendering of the aerial vehicle

- motion_blur.py for image-effect augmentation

- hmi.py for human-machine interaction or command handling

These modules represent the heart of the visual validation pipeline.

6. Data flow inside the app

The likely flow is: user input in the GUI → launcher/main orchestration → environment setup → simulator loop → rendering / image effects → feedback back to the UI. hmi.py is the control bridge between operator intent and simulation commands, while render_drone.py and motion_blur.py shape the generated visual output.

7. External simulation / autopilot integration

The gazebo/ and pegasus/ directories indicate integration with PX4/MAVLink-based simulation stacks. Files like pymavlink_px4_interface.py, viva_sitl.py, and pegasus_viva.py suggest adapters for connecting the ViVa simulation flow to external flight-control or SITL environments. These are important architectural boundaries because they connect the visual simulation platform to vehicle/autopilot ecosystems.

8. Scenario and backend variants

The duplicated interface files under both gazebo/ and pegasus/ imply multiple backend-specific adapters or experiment setups. If diagramming the system, model these as integration layers rather than core logic: the core app likely stays in viva/, while backend folders translate between ViVa and external simulators.

9. Tests as architecture validation

tests/test_01.py, test_02.py, and test_03.py suggest a small but explicit test suite covering core behavior. These tests are the main verification boundary for the package and likely exercise package importability, simulation logic, or interface behavior.

10. Documentation and publication pipeline

docs/ and mkdocs.yml indicate MkDocs-based project documentation, with content split across installation, usage, API, and about pages. The GitHub Actions workflows in .github/workflows/ci.yml and publish.yml handle automated validation and package release/publishing.

11. Packaging/tooling

pyproject.toml, .python-version, and ruff.toml show a modern Python packaging and linting setup. This is a standard library-level concern, but architecturally it matters because the project is distributed as a Python package and governed by code-quality automation.

12. How to draw the boundaries

For an architecture diagram, the cleanest split is:

- Operator/UI layer: viva/gui.py, viva/GUI/

- Core simulation engine: viva/modules/*, viva/simulator logic

- Runtime orchestration/config: viva/main.py, viva/launcher.py, viva/env.py

- External integration adapters: gazebo/, pegasus/

- Support systems: tests/, docs/, CI workflows

The main dependency direction is from UI/orchestration into the simulation modules, and from adapters outward to PX4/MAVLink/Gazebo-style external systems.