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 files and 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)
  • Adding lane-to-lane connections (connection.add)
  • Delete lane-to-lane connections (connection.delete)

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.

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 specific properties, depending on the element type. Supported element types are: edge, lane, junction and tls_connection. The properties.element field acts as a discriminator for the element type.

See the following example for a GET response.

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
{
  "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" ],
        "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); an empty list indicates that no vehicle class is permitted on this lane
  • outgoingLanes – list of connected lane IDs
  • 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.

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

(will be extended in the future)

TLS connection features

Properties may include:

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

(will be extended in the future)

Notes for Clients

Geometries are 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.

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

A PATCH request for the editor/scenario/<id> endpoint applies incremental, versioned modifications to an existing scenario network. Instead of submitting a modified GeoJSON, clients have to 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 increments the new scenario version.

Lane Properties

The lane.set operation modifies lane-specific attributes such as speed limits and allowed vehicle classes. An example request body is shown below.

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 Closures

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 the 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)

Please see the example below for a patch request which closes lane edge123#1_0 and opens lane edge4313#1_1.

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"},
  ]
}
Manage Connections

The connection.add and connection.delete operations modify directed lane-to-lane connections within the scenario network. Lane connections define permitted routing transitions at junctions and directly influence vehicle turning behavior and route feasibility.

Existing connections are reflected in the outgoingLanes property of lane features in the GeoJSON representation. connection.add creates a new directed connection between a source lane and a target lane. connection.delete removes an existing directed connection between two lanes.

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "base_version": 5,
  "operations": [
    {
      "operation": "connection.add",
      "from": "109#2_0",
      "to": "-122#3_0"
    },
    {
      "operation": "connection.delete",
      "from": "123#1_0",
      "to": "544#5_1"
    }
  ]
}

Parameters:

  • from - source lane ID
  • to - target lane ID

For connection.add the connection must not already exist and it must be topologically valid (i.e., lanes must be connectable at a common junction). Invalid operations are rejected with HTTP 400. Connection edits result in modifications of <connection> elements in the underlying SUMO network.

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

Applying editor operations can be a long-running task because it may require rebuilding the SUMO network (e.g., via netconvert), validating demand feasibility and conditionally repairing demand using duarouter, and regenerating derived artifacts (thumbnails, GeoJSON, metadata).

Clients should poll the returned status_url until the state becomes SUCCESS or FAILURE. Therefore, the PATCH request is processed asynchronously.

Example response while processing (state PROGRESS):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "result_id": "3f1e8b5e-7b6d-4d3e-a2d9-5c9b8c4f6e21",
  "state": "PROGRESS",
  "log": "Applying network patches via netconvert",
  "stages": [
    { "id": "LOCATING_NETWORK", "label": "Locating network file", "state": "SUCCESS" },
    { "id": "LOCATING_ROUTE_FILES", "label": "Locating route files", "state": "SUCCESS" },
    { "id": "CREATING_NETWORK_PATCHES", "label": "Creating network patches", "state": "SUCCESS" },
    { "id": "APPLYING_NETWORK_PATCHES", "label": "Applying network patches", "state": "PROGRESS" },
    { "id": "REPAIRING_DEMAND", "label": "Repairing demand", "state": "PENDING" },
    { "id": "CREATING_SCENARIO_THUMBNAIL", "label": "Creating scenario images", "state": "PENDING" },
    { "id": "EXPORTING_SCENARIO_NETWORK_AS_GEOJSON", "label": "Exporting scenario network to geojson format", "state": "PENDING" },
    { "id": "UPDATING_SCENARIO_PROPERTIES", "label": "Updating scenario properties", "state": "PENDING" }
  ]
}

Final response on success (state SUCCESS):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "result_id": "3f1e8b5e-7b6d-4d3e-a2d9-5c9b8c4f6e21",
  "state": "SUCCESS",
  "log": "Scenario edit finished",
  "scenario_id": 123,
  "scenario_name": "Editor Scenario Lane Close/Open ...",
  "scenario_version": 6,
  "stages": [
    { "id": "LOCATING_NETWORK", "label": "Locating network file", "state": "SUCCESS" },
    { "id": "LOCATING_ROUTE_FILES", "label": "Locating route files", "state": "SUCCESS" },
    { "id": "CREATING_NETWORK_PATCHES", "label": "Creating network patches", "state": "SUCCESS" },
    { "id": "APPLYING_NETWORK_PATCHES", "label": "Applying network patches", "state": "SUCCESS" },
    { "id": "REPAIRING_DEMAND", "label": "Repairing demand", "state": "SUCCESS" },
    { "id": "CREATING_SCENARIO_THUMBNAIL", "label": "Creating scenario images", "state": "SUCCESS" },
    { "id": "EXPORTING_SCENARIO_NETWORK_AS_GEOJSON", "label": "Exporting scenario network to geojson format", "state": "SUCCESS" },
    { "id": "UPDATING_SCENARIO_PROPERTIES", "label": "Updating scenario properties", "state": "SUCCESS" }
  ]
}
  • state reports the overall task state (e.g., PENDING, PROGRESS, SUCCESS, FAILURE)
  • log may provide a short human-readable progress message
  • stages provides a structured breakdown aligned with the runner pipeline
  • On FAILURE, an error_message field is provided with diagnostic information

Note

The original, user-provided demand definition 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.