# tumftm/ethicaltrajectoryplanning architecture

> Architecture diagram of the GitHub repository tumftm/ethicaltrajectoryplanning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tumftm/ethicaltrajectoryplanning
- Repository: https://github.com/tumftm/ethicaltrajectoryplanning

## Overview

##### Project type and purpose
- This is a Python-based autonomous vehicle trajectory planning tool with an ethical risk-assessment core. It combines two planning layers (GlobalPath + Frenet), a risk assessment module, configuration management, prediction networks, and a suite of analysis/visualization scripts. It runs as a CLI application on CommonRoad scenarios, producing logs, plots, and trajectories.

##### Main components
a. Inputs & Configuration
- CommonRoad scenario repository (external folder)
- JSON config files under planner/Frenet/configs
b. Core Planning Layers
- GlobalPath planner (planner/GlobalPath)
– Lateral/longitudinal path generation via quintic polynomials
- Frenet corridor planner (planner/Frenet)
– Path sampling + trajectory cost evaluation
– Prediction network (GPU-enabled) for dynamic obstacles
– Cost terms including collision risk and harm estimation
– Bayesian optimization for parameter tuning (plannertools)
c. Risk Assessment Module (risk_assessment)
- collision_probability, harm_estimation, risk_costs
- helper functions & logistic regression models
- visualization dashboards (risk_assessment/visualization)
d. Tools & Utilities
- Analysis tools (planner/Frenet/analyze_tools)
- Plotting tools (planner/Frenet/plot_tools)
- Scenario handler, animate, evaluate, write_solution (planner/plannertools)
- Common utilities (planner/utils, risk_assessment/utils)
e. Output & Storage
- Logs (planner/Frenet/results)
- Evaluation metrics (JSON, boxplots, dashboards)

##### Relationships & Data Flow
1. Load CommonRoad scenario →
2. Load configs →
3. GlobalPath planner produces rough path →
4. Frenet planner samples trajectories around rough path →
- Calls prediction network
- Invokes risk_assessment (collision & harm) to compute cost
- Optionally runs Bayesian optimization to tune weights
5. Select best trajectory → write_solution →
6. Log results →
7. Post–processing: analyze_tools → plot_tools → final metrics/plots

##### Architectural patterns & design principles
- Modular subpackages for separation of concerns (planner.Frenet, planner.GlobalPath, risk_assessment)
- Configuration‐driven behavior (JSON files)
- Script‐based orchestration (entry scripts like frenet_planner.py)
- Reusable utilities & helper libraries
- GPU‐accelerated prediction as an external “service”

##### Essential elements
- Component labels (e.g., “planner/GlobalPath”, “risk_assessment/collision_probability”)
- On console/CLI entry points (frenet_planner.py, evaluatefrenet.py)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Inputs
    scenarios["CommonRoad Scenarios"]:::external
    configs["JSON Configs\n(planner/Frenet/configs)"]:::external

    %% Orchestration
    cli["CLI Entry Points\nfrenet_planner.py,\nevaluatefrenet.py\n(Python 3.8)"]:::external

    %% Core Planning Modules
    subgraph "Core Planning Modules"
        direction TB
        subgraph "GlobalPath Planner" 
            direction TB
            gp_utils["quintic_polynomials_planner.py"]:::core
            gp_lanelet["lanelet_based_planner.py"]:::core
            gp_eval["evaluate.py"]:::core
        end
        subgraph "Frenet Corridor Planner"
            direction TB
            frenet_main["frenet_planner.py\n(Bayesian Optimization)"]:::core
            frenet_funcs["frenet_functions.py"]:::core
            polynomials["polynomials.py"]:::core
            prediction_helper["prediction_helpers.py\n(TensorFlow/PyTorch)"]:::risk
            subgraph "Bayesian Optimization"
                direction TB
                bayes_tool1["bayes_optimization.py"]:::tools
                bayes_tool2["bayesian_optimization.py"]:::tools
            end
        end
    end

    %% Risk Assessment Module
    subgraph "Risk Assessment Module"
        direction TB
        collision["collision_probability.py"]:::risk
        harm["harm_estimation.py"]:::risk
        costs["risk_costs.py"]:::risk
        subgraph "Helpers & Models"
            direction TB
            coll_helpers["coll_prob_helpers.py"]:::risk
            coll_helper_fn["collision_helper_function.py"]:::risk
            harm_params["harm_parameters.py"]:::risk
            properties["properties.py"]:::risk
            lr1["logistic_regression.py"]:::risk
            lr2["logistic_regression_asymmetrical.py"]:::risk
            lr3["logistic_regression_symmetrical.py"]:::risk
        end
        subgraph "Visualization Dashboards"
            direction TB
            dash1["risk_dashboard.py"]:::risk
            dash2["collision_visualization.py"]:::risk
            dash3["risk_visualization.py"]:::risk
        end
    end

    %% Tools & Utilities
    subgraph "Scenario & I/O Tools"
        direction TB
        handler["scenario_handler.py"]:::tools
        animate["animate.py"]:::tools
        eval_io["evaluate.py"]:::tools
        write_sol["write_solution.py"]:::tools
        animatef["animatefrenet.py"]:::tools
        evalf["evaluatefrenet.py"]:::tools
        frenetcreator["frenetcreator.py"]:::tools
    end

    subgraph "Post-processing"
        direction TB
        subgraph "Analysis Tools"
            direction TB
            analyze1["analyze_correlations.py"]:::tools
            analyze2["analyze_log.py"]:::tools
            analyze3["analyze_risk_dist.py"]:::tools
        end
        subgraph "Plotting Tools"
            direction TB
            plot1["boxplots_correlations.py"]:::tools
            plot2["boxplots_risks.py"]:::tools
            colors["colors.py"]:::tools
        end
    end

    %% Common Utilities
    subgraph "Common Utilities"
        direction TB
        util1["planner/utils"]:::external
        util2["helper_functions.py"]:::external
        util3["risk_assessment/utils"]:::external
    end

    %% Storage
    results(("Logs & Results")):::storage

    %% Data Flow
    scenarios --> configs --> cli
    configs --> gp_lanelet
    cli --> gp_lanelet --> gp_utils --> gp_eval --> frenet_main
    frenet_main --> frenet_funcs --> polynomials
    frenet_main --> prediction_helper --> collision
    frenet_main --> collision --> harm --> costs
    frenet_main --> bayes_tool1
    frenet_main --> bayes_tool2
    costs --> write_sol --> results
    results --> analyze1 --> analyze2 --> analyze3 --> plot1 --> plot2 --> colors
    write_sol --> animate
    write_sol --> eval_io

    %% Dependencies on utilities
    gp_lanelet --> util1
    frenet_main --> util2
    collision --> util3

    %% Click Events
    click configs "https://github.com/tumftm/ethicaltrajectoryplanning/tree/master/planner/Frenet/configs"
    click gp_lanelet "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/GlobalPath/lanelet_based_planner.py"
    click gp_eval "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/GlobalPath/evaluate.py"
    click gp_utils "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/GlobalPath/utils/quintic_polynomials_planner.py"
    click frenet_main "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/frenet_planner.py"
    click frenet_funcs "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/utils/frenet_functions.py"
    click polynomials "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/utils/polynomials.py"
    click prediction_helper "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/utils/prediction_helpers.py"
    click bayes_tool1 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/analyze_tools/bayes_optimization.py"
    click bayes_tool2 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/plannertools/bayesian_optimization.py"
    click collision "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/collision_probability.py"
    click harm "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/harm_estimation.py"
    click costs "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/risk_costs.py"
    click coll_helpers "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/helpers/coll_prob_helpers.py"
    click coll_helper_fn "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/helpers/collision_helper_function.py"
    click harm_params "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/helpers/harm_parameters.py"
    click properties "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/helpers/properties.py"
    click lr1 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/utils/logistic_regression.py"
    click lr2 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/utils/logistic_regression_asymmetrical.py"
    click lr3 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/utils/logistic_regression_symmetrical.py"
    click dash1 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/visualization/risk_dashboard.py"
    click dash2 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/visualization/collision_visualization.py"
    click dash3 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/risk_assessment/visualization/risk_visualization.py"
    click analyze1 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/analyze_tools/analyze_correlations.py"
    click analyze2 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/analyze_tools/analyze_log.py"
    click analyze3 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/analyze_tools/analyze_risk_dist.py"
    click plot1 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/plot_tools/boxplots_correlations.py"
    click plot2 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/plot_tools/boxplots_risks.py"
    click colors "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/plot_tools/colors.py"
    click handler "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/plannertools/scenario_handler.py"
    click animate "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/plannertools/animate.py"
    click eval_io "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/plannertools/evaluate.py"
    click write_sol "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/plannertools/write_solution.py"
    click animatef "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/plannertools/animatefrenet.py"
    click evalf "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/plannertools/evaluatefrenet.py"
    click frenetcreator "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/plannertools/frenetcreator.py"
    click util1 "https://github.com/tumftm/ethicaltrajectoryplanning/tree/master/planner/utils"
    click util2 "https://github.com/tumftm/ethicaltrajectoryplanning/blob/master/planner/Frenet/utils/helper_functions.py"
    click util3 "https://github.com/tumftm/ethicaltrajectoryplanning/tree/master/risk_assessment/utils"
    
    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef risk fill:#90EE90,stroke:#000
    classDef tools fill:#FFA500,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
    classDef storage fill:#eeeeee,stroke:#000,stroke-dasharray: 5 5
```
