Skip to content

Editor

The Editor module enables network-level, versioned modifications to existing scenarios. It allows users to apply targeted structural changes to the simulation network (e.g., roadworks, incidents, traffic control measures, or policy interventions) without rebuilding the scenario from scratch.

Edits are submitted via the endpoint editor/scenario/<id> and are executed sequentially per scenario. Each edit is based on a specific scenario version and produces a new version. This guarantees reproducibility and prevents conflicting concurrent changes.

Internally, an edit may:

  • generate explicit SUMO network patch files,
  • apply them using netconvert,
  • validate demand feasibility and optionally repair demand files (duarouter),
  • regenerate derived artifacts (thumbnails, GeoJSON, metadata).

Currently supported patch types:

  • Adjusting lane speed limits (lane.set)
  • Changing allowed vehicle classes (lane.set)
  • Closing lanes via SUMO rerouters (lane.close)
  • Re-opening lanes via SUMO rerouters (lane.open)

Endpoint: editor/scenario/<id>

Authorization

This endpoint requires authentication and an enabled Scenario Editor feature in the plan. Access is restricted to scenarios owned by the authenticated user. Built-in scenarios are excluded from editing.

Method: GET

Retrieves the editable network representation of a scenario as a detailed GeoJSON FeatureCollection.

The response represents the current server-side state of the scenario network, including all previously applied edits. It is the authoritative input for client-side editing and validation. The returned GeoJSON always includes the current scenario version, which must be supplied as base_version when submitting edit operations via PATCH.

Lane features may include an optional closed property which is present only if the lane is closed via a SUMO rerouter.

GET Response

The response is a GeoJSON FeatureCollection with an additional top-level version field. The version is an Integer ≥ 1 and reflects the current scenario network version on the server. It is used for optimistic locking in subsequent PATCH requests.

Each entry in features is a standard GeoJSON Feature with polymorphic properties, depending on the element type. Supported element types are: edge, lane, junction and tls_connection. The properties.element field acts as a discriminator.

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
// - Example Response - //
{
  "version": 5,
  "type": "FeatureCollection",
  "features": [
    {
      "geometry": {
        "coordinates": [
          [
            [ 13.334833, 52.503476 ],
            ...
          ]
        ],
        "type": "Polygon"
      },
      "properties": {
        "allow":  [ "bicycle", "bus", "passenger" ],
        "element": "edge",
        "id": "-111812579#1",
        "name": "Rankestraße",
        "numLanes": 1,
        "fromNode": "121",
        "toNode": "5622"
      },
      "type": "Feature"
    },
    ...
    {
      "geometry": {
        "coordinates": [
          [
            [ 13.33999, 52.503991 ],
            ...
          ]
        ],
        "type": "Polygon"
      },
      "properties": {
        "allow": [ "pedestrian" ],
        "element": "lane",
        "id": "109#2_0",
        "index": 0,
        "maxSpeed": 2.78,
        "outgoingLanes": [ "-122#3_0", "123#2_0", "544#5_1" ],
        "directions": [ "r", "l", "s" ],
        "closed": true,
      },
      "type": "Feature"
    },
    ...
    {
      "geometry": {
        "coordinates": [
          [
            [ 13.334833, 52.503476 ],
            ...
          ]
        ],
        "type": "Polygon"
      },
      "properties": {
        "element": "junction",
        "id": "7845"
      },
      "type": "Feature"
    },
    ...
  ]
}
Lane features

Lane features are the primary editable elements. Properties may include:

  • id – lane ID (<edgeId>_<index>)
  • index – lane index
  • maxSpeed – maximum allowed speed (m/s)
  • allow – list of allowed SUMO vehicle classes (may be empty)
  • outgoingLanes – list of connected lane IDs
  • directions – logical turn directions (l, r, s, L, R, T)
  • width – lane width (m)
  • centerLine – lane center geometry (optional)
  • closed – optional boolean, present only if the lane is closed via a rerouter

All list-valued properties are returned as arrays, never as comma-separated strings. An empty allow list indicates that no vehicle class is permitted on this lane.

Edge features

Properties may include:

  • id – edge ID
  • name – street name (optional)
  • numLanes – number of lanes
  • fromNode, toNode – junction IDs
  • allow – list of allowed vehicle classes (if present)

The allow list of an edge is computed as the union of the allow lists of its constituent lanes.

Junction features

Properties:

  • id – junction ID
TLS connection features

Properties may include:

  • id
  • tls – traffic light system ID
  • tlIndex – signal index
Geometry

Geometry is provided as GeoJSON-compatible objects. Edges and lanes are typically represented as polygons. Junctions are represented by their geometric footprint.

The geometry is intended for visualization and interaction, not for direct network reconstruction.

Notes for Clients

The returned network reflects the latest successfully applied edit. Clients must treat the response as read-only input. Any modification must be expressed via PATCH operations using the provided version. Concurrent edits are prevented server-side via explicit edit locks.

Method: PATCH

The PATCH editor/scenario/<id> endpoint applies incremental, versioned modifications to an existing scenario network. Instead of submitting a modified GeoJSON, clients describe the intended changes explicitly as a list of patch operations.

Each PATCH request:

  • is based on a specific scenario version (base_version),
  • applies one or more atomic edit operations,
  • creates exactly one new scenario version,
  • is executed asynchronously in the background.

PATCH Request

Each PATCH request must specify the base_version of the scenario it is based on. If the server-side scenario version has changed since that version, the request is rejected with HTTP 409 (Conflict). To ensure a strictly linear edit history, only one PATCH request may be processed per scenario at any given time. Concurrent edit attempts are rejected with HTTP 423 (Locked).

Every successfully applied PATCH request creates a new scenario version (base_version + 1).

lane.set

The lane.set operation modifies lane-specific attributes such as speed limits and allowed vehicle classes.

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "base_version": 5,
  "operations": [
    {
      "operation": "lane.set",
      "id": "123#4_2",
      "set": {
        "maxSpeed": 8.33,
        "allow": ["bicycle", "bus", "passenger"]
      }
    }
  ]
}

In the SESAM backend, this results in the following patch being applied to the SUMO scenario network:

XML
1
2
3
4
5
<edges>
  <edge id="123#4">
    <lane index="2" allow="bicycle bus passenger" speed="8.33" />
  </edge>
</edges>
lane.close / lane.open

The lane.close and lane.open operations control lane availability by dynamically restricting or restoring access for all vehicle classes within the simulation. Closed lanes are excluded from routing and simulation until they are reopened. Lane closures are implemented using SUMO rerouters instead of modifying the network topology. This allows for reversible restrictions (e.g., roadworks, incidents).

A dedicated SUMO additional file is added to the scenario, containing a single rerouter with id sesam_lane_closures. All closed lanes are represented as <closingLaneReroute> entries inside a single time interval spanning over the whole simulation time.

  • lane.close adds a closure entry (idempotent)
  • lane.open removes the closure entry (if no closures remain, the rerouter file is removed and unregistered)
JSON
1
2
3
4
5
6
7
{
  "base_version": 5,
  "operations": [
    {"operation": "lane.close", "id": "edge123#1_0"},
    {"operation": "lane.open", "id": "edge4313#1_1"},
  ]
}

Demand validation and repair

After applying all operations, the SESAM backend checks whether all routes and trips remain feasible given possible lane closures in the network. If infeasible demand elements are detected, the affected demand files are repaired using duarouter. The original, user-provided demand is never discarded. SESAM preserves the original demand definition and uses it as the baseline for subsequent edits and saves. Any demand repair is applied only to the derived, scenario-internal artifacts required for simulation, ensuring that no demand information is permanently removed or simplified.

PATCH Response

If the request is accepted, the server returns immediately with HTTP 202 (Accepted):

JSON
1
2
3
4
{
  "result_id": "<uuid>",
  "status_url": "http://<server-url>/api/v1/editor/scenario-status/<uuid>"
}
  • result_id - Unique ID of the background task
  • status_url- Endpoint for tracking progress and retrieving the final result