# mareklorenz/scenario-modification-framework architecture

> Architecture diagram of the GitHub repository mareklorenz/scenario-modification-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mareklorenz/scenario-modification-framework
- Repository: https://github.com/mareklorenz/scenario-modification-framework

## Overview

This is an LLM-assisted CommonRoad driving-scenario analysis and modification framework. An engineer supplies a scenario XML and precomputed ego trajectory; the main workflow derives scenario layers and safety metrics, uses LLM prompts to identify a critical obstacle and interval, requests an adversarial trajectory update, then writes an updated scenario and records results. Supporting branches include ego-trajectory preprocessing, MTL safety analysis, and simulation/evaluation. Edges reflect README workflow statements and source references; unsampled implementation details are not asserted.

Main entry points: [`main.py`](https://github.com/mareklorenz/scenario-modification-framework/blob/main/main.py) (Workflow Orchestrator), [`llm_templates/llm_utils.py`](https://github.com/mareklorenz/scenario-modification-framework/blob/main/llm_templates/llm_utils.py) (LLM Client), [`scenario_modification/modify_scenario.py`](https://github.com/mareklorenz/scenario-modification-framework/blob/main/scenario_modification/modify_scenario.py) (Trajectory Modification), [`mtl_converter/L4_converter.py`](https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L4_converter.py) (Obstacle MTL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Scenario Workflow"]
  node_main["Workflow Orchestrator<br/>[main.py]"]
  node_scenario_xml["CommonRoad Scenario"]
  node_ego_csv["Ego Trajectory"]
  node_modified_scenario["Updated Scenario"]
end

subgraph group_analysis["Scenario Analysis"]
  node_layer_model["Scenario Layers<br/>[layermodel.py]"]
  node_xml_json["XML Conversion<br/>[xml2json.py]"]
  node_l1_mtl["Road MTL<br/>[L1_converter.py]"]
  node_l4_mtl["Obstacle MTL<br/>[L4_converter.py]"]
  node_l7_mtl["Ego MTL<br/>[L7_converter.py]"]
  node_safety_metrics["Safety Metrics<br/>[safety_metrics.py]"]
  node_ttc_metrics["TTC Metrics"]
  node_lanelet_utils["Lanelet Geometry<br/>[utils.py]"]
  node_critical_obstacles["Obstacle Selection"]
  node_critical_interval["Interval Selection"]
  node_generation_types["Result Schemas<br/>[generation.py]"]
end

subgraph group_modification["Scenario Modification"]
  node_modify["Trajectory Modification<br/>[modify_scenario.py]"]
  node_llm_utils["LLM Client<br/>[llm_utils.py]"]
  node_update_xml["Scenario Writer<br/>[update_xml.py]"]
end

subgraph group_support["Trajectory and Evaluation"]
  node_trajectory_extract["Trajectory Extraction"]
  node_plot["Trajectory Visualization<br/>[plot.py]"]
  node_ego_preprocess["Ego Preparation"]
  node_output_analysis["Result Analysis<br/>[output_analysis.py]"]
  node_simulation["Scenario Simulation<br/>[run_simulation.py]"]
end

node_engineer(("Scenario Engineer"))
node_openai{{"OpenAI API"}}
node_gemini{{"Gemini API"}}
node_ollama{{"Local Ollama"}}

node_engineer -->|"runs"| node_main
node_engineer -->|"provides"| node_scenario_xml
node_engineer -->|"provides"| node_ego_csv
node_main -->|"reads"| node_scenario_xml
node_main -->|"reads"| node_ego_csv
node_main -->|"uses"| node_layer_model
node_main -->|"uses"| node_xml_json
node_main -->|"converts"| node_l1_mtl
node_main -->|"converts"| node_l4_mtl
node_main -->|"converts"| node_l7_mtl
node_main -->|"calculates"| node_safety_metrics
node_l4_mtl -->|"uses"| node_ttc_metrics
node_l4_mtl -->|"checks lanelets"| node_lanelet_utils
node_update_xml -->|"checks lanelets"| node_lanelet_utils
node_main -->|"requests selection"| node_critical_obstacles
node_main -->|"requests interval"| node_critical_interval
node_critical_interval -->|"parses result"| node_generation_types
node_critical_interval -->|"calls"| node_llm_utils
node_critical_obstacles -->|"calls"| node_llm_utils
node_main -->|"requests update"| node_modify
node_modify -->|"requests trajectory"| node_llm_utils
node_modify -->|"gets lanelets"| node_l1_mtl
node_modify -->|"uses results"| node_generation_types
node_llm_utils -->|"sends requests"| node_openai
node_llm_utils -->|"sends requests"| node_gemini
node_llm_utils -->|"sends requests"| node_ollama
node_main -->|"writes scenario"| node_update_xml
node_update_xml -->|"reads source"| node_scenario_xml
node_main -->|"saves result"| node_modified_scenario
node_main -->|"records results"| node_output_analysis
node_main -->|"extracts trajectories"| node_trajectory_extract
node_trajectory_extract -->|"uses geometry"| node_plot
node_ego_preprocess -->|"prepares input"| node_trajectory_extract
node_ego_preprocess -->|"visualizes"| node_plot
node_engineer -.->|"runs batch"| node_simulation

click node_main "https://github.com/mareklorenz/scenario-modification-framework/blob/main/main.py"
click node_scenario_xml "https://github.com/mareklorenz/scenario-modification-framework/tree/main/data/scenarios"
click node_ego_csv "https://github.com/mareklorenz/scenario-modification-framework/tree/main/data/ego_trajectories"
click node_layer_model "https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/layermodel.py"
click node_xml_json "https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/xml2json.py"
click node_l1_mtl "https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L1_converter.py"
click node_l4_mtl "https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L4_converter.py"
click node_l7_mtl "https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L7_converter.py"
click node_safety_metrics "https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/safety_metrics.py"
click node_ttc_metrics "https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L4_safety_metrics.py"
click node_lanelet_utils "https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/utils.py"
click node_critical_obstacles "https://github.com/mareklorenz/scenario-modification-framework/blob/main/llm_templates/critical_obstacles.py"
click node_critical_interval "https://github.com/mareklorenz/scenario-modification-framework/blob/main/llm_templates/critical_interval.py"
click node_generation_types "https://github.com/mareklorenz/scenario-modification-framework/blob/main/generation_types/generation.py"
click node_trajectory_extract "https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/extract_trajectories.py"
click node_plot "https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/plot.py"
click node_ego_preprocess "https://github.com/mareklorenz/scenario-modification-framework/blob/main/generate_ego_trajectory.py"
click node_modify "https://github.com/mareklorenz/scenario-modification-framework/blob/main/scenario_modification/modify_scenario.py"
click node_llm_utils "https://github.com/mareklorenz/scenario-modification-framework/blob/main/llm_templates/llm_utils.py"
click node_update_xml "https://github.com/mareklorenz/scenario-modification-framework/blob/main/scenario_modification/update_xml.py"
click node_output_analysis "https://github.com/mareklorenz/scenario-modification-framework/blob/main/output_analysis.py"
click node_simulation "https://github.com/mareklorenz/scenario-modification-framework/blob/main/scripts/simulation/run_simulation.py"
click node_modified_scenario "https://github.com/mareklorenz/scenario-modification-framework/tree/main/data/outputs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_scenario_xml,node_ego_csv,node_modified_scenario toneBlue
class node_layer_model,node_xml_json,node_l1_mtl,node_l4_mtl,node_l7_mtl,node_safety_metrics,node_ttc_metrics,node_lanelet_utils,node_critical_obstacles,node_critical_interval,node_generation_types toneAmber
class node_modify,node_llm_utils,node_update_xml,node_openai,node_gemini toneMint
class node_trajectory_extract,node_plot,node_ego_preprocess,node_output_analysis,node_simulation toneRose
class node_engineer,node_ollama toneIndigo
```

## Components

### Scenario Workflow

- [Workflow Orchestrator](https://github.com/mareklorenz/scenario-modification-framework/blob/main/main.py): `main.py`
- [CommonRoad Scenario](https://github.com/mareklorenz/scenario-modification-framework/tree/main/data/scenarios): `data/scenarios`
- [Ego Trajectory](https://github.com/mareklorenz/scenario-modification-framework/tree/main/data/ego_trajectories): `data/ego_trajectories`
- [Updated Scenario](https://github.com/mareklorenz/scenario-modification-framework/tree/main/data/outputs): `data/outputs`

### Scenario Analysis

- [Scenario Layers](https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/layermodel.py): `preprocessing/layermodel.py`
- [XML Conversion](https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/xml2json.py): `preprocessing/xml2json.py`
- [Road MTL](https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L1_converter.py): `mtl_converter/L1_converter.py`
- [Obstacle MTL](https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L4_converter.py): `mtl_converter/L4_converter.py`
- [Ego MTL](https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L7_converter.py): `mtl_converter/L7_converter.py`
- [Safety Metrics](https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/safety_metrics.py): `mtl_converter/safety_metrics.py`
- [TTC Metrics](https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/L4_safety_metrics.py): `mtl_converter/L4_safety_metrics.py`
- [Lanelet Geometry](https://github.com/mareklorenz/scenario-modification-framework/blob/main/mtl_converter/utils.py): `mtl_converter/utils.py`
- [Obstacle Selection](https://github.com/mareklorenz/scenario-modification-framework/blob/main/llm_templates/critical_obstacles.py): `llm_templates/critical_obstacles.py`
- [Interval Selection](https://github.com/mareklorenz/scenario-modification-framework/blob/main/llm_templates/critical_interval.py): `llm_templates/critical_interval.py`
- [Result Schemas](https://github.com/mareklorenz/scenario-modification-framework/blob/main/generation_types/generation.py): `generation_types/generation.py`

### Scenario Modification

- [Trajectory Modification](https://github.com/mareklorenz/scenario-modification-framework/blob/main/scenario_modification/modify_scenario.py): `scenario_modification/modify_scenario.py`
- [LLM Client](https://github.com/mareklorenz/scenario-modification-framework/blob/main/llm_templates/llm_utils.py): `llm_templates/llm_utils.py`
- [Scenario Writer](https://github.com/mareklorenz/scenario-modification-framework/blob/main/scenario_modification/update_xml.py): `scenario_modification/update_xml.py`

### Trajectory and Evaluation

- [Trajectory Extraction](https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/extract_trajectories.py): `preprocessing/extract_trajectories.py`
- [Trajectory Visualization](https://github.com/mareklorenz/scenario-modification-framework/blob/main/preprocessing/plot.py): `preprocessing/plot.py`
- [Ego Preparation](https://github.com/mareklorenz/scenario-modification-framework/blob/main/generate_ego_trajectory.py): `generate_ego_trajectory.py`
- [Result Analysis](https://github.com/mareklorenz/scenario-modification-framework/blob/main/output_analysis.py): `output_analysis.py`
- [Scenario Simulation](https://github.com/mareklorenz/scenario-modification-framework/blob/main/scripts/simulation/run_simulation.py): `scripts/simulation/run_simulation.py`

### Other components

- **Scenario Engineer**
- **OpenAI API**
- **Gemini API**
- **Local Ollama**

## Connections

- Scenario Engineer → Workflow Orchestrator: runs (evidence: `README.md`)
- Scenario Engineer → CommonRoad Scenario: provides (evidence: `README.md`)
- Scenario Engineer → Ego Trajectory: provides (evidence: `README.md`)
- Workflow Orchestrator → CommonRoad Scenario: reads (evidence: `README.md`)
- Workflow Orchestrator → Ego Trajectory: reads (evidence: `README.md`)
- Workflow Orchestrator → Scenario Layers: uses (evidence: `main.py`)
- Workflow Orchestrator → XML Conversion: uses (evidence: `main.py`)
- Workflow Orchestrator → Road MTL: converts (evidence: `main.py`)
- Workflow Orchestrator → Obstacle MTL: converts (evidence: `main.py`)
- Workflow Orchestrator → Ego MTL: converts (evidence: `main.py`)
- Workflow Orchestrator → Safety Metrics: calculates (evidence: `main.py`)
- Obstacle MTL → TTC Metrics: uses (evidence: `mtl_converter/L4_converter.py`)
- Obstacle MTL → Lanelet Geometry: checks lanelets (evidence: `mtl_converter/L4_converter.py`)
- Scenario Writer → Lanelet Geometry: checks lanelets (evidence: `scenario_modification/update_xml.py`)
- Workflow Orchestrator → Obstacle Selection: requests selection (evidence: `main.py`)
- Workflow Orchestrator → Interval Selection: requests interval (evidence: `main.py`)
- Interval Selection → Result Schemas: parses result (evidence: `llm_templates/critical_interval.py`)
- Interval Selection → LLM Client: calls (evidence: `llm_templates/critical_interval.py`)
- Obstacle Selection → LLM Client: calls (evidence: `llm_templates/critical_obstacles.py`)
- Workflow Orchestrator → Trajectory Modification: requests update (evidence: `main.py`)
- Trajectory Modification → LLM Client: requests trajectory (evidence: `scenario_modification/modify_scenario.py`)
- Trajectory Modification → Road MTL: gets lanelets (evidence: `scenario_modification/modify_scenario.py`)
- Trajectory Modification → Result Schemas: uses results (evidence: `scenario_modification/modify_scenario.py`)
- LLM Client → OpenAI API: sends requests (evidence: `llm_templates/llm_utils.py`)
- LLM Client → Gemini API: sends requests (evidence: `llm_templates/llm_utils.py`)
- LLM Client → Local Ollama: sends requests (evidence: `llm_templates/llm_utils.py`)
- Workflow Orchestrator → Scenario Writer: writes scenario (evidence: `main.py`)
- Scenario Writer → CommonRoad Scenario: reads source (evidence: `scenario_modification/update_xml.py`)
- Workflow Orchestrator → Updated Scenario: saves result (evidence: `README.md`)
- Workflow Orchestrator → Result Analysis: records results (evidence: `main.py`)
- Workflow Orchestrator → Trajectory Extraction: extracts trajectories (evidence: `main.py`)
- Trajectory Extraction → Trajectory Visualization: uses geometry (evidence: `preprocessing/extract_trajectories.py`)
- Ego Preparation → Trajectory Extraction: prepares input (evidence: `generate_ego_trajectory.py`)
- Ego Preparation → Trajectory Visualization: visualizes (evidence: `generate_ego_trajectory.py`)
- Scenario Engineer → Scenario Simulation: runs batch (evidence: `README.md`)
