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 — for example, to simulate roadworks, incidents, traffic control measures, or policy interventions — without rebuilding the scenario from scratch.

Edits are applied via the editor/scenario/<id> endpoint and are executed sequentially per scenario. Each edit is based on a specific scenario version and results in a new version, ensuring reproducibility and preventing conflicting concurrent changes.

Internally, the Editor:

  • generates explicit SUMO network patch files,
  • applies them using netconvert,
  • optionally validates and repairs demand files,
  • and regenerates all derived artifacts (thumbnails, GeoJSON, metadata).

The system currently supports the following patch types:

  • Adjusting lane speed limits
  • Changing allowed vehicle classes (vClass restrictions)

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:

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
// - 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" ]
      },
      "type": "Feature"
    },
    ...
    {
      "geometry": {
        "coordinates": [
          [
            [ 13.334833, 52.503476 ],
            ...
          ]
        ],
        "type": "Polygon"
      },
      "properties": {
        "element": "junction",
        "id": "7845"
      },
      "type": "Feature"
    },
    ...
  ]
}

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.

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)

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.

This design enables optimistic locking, reproducible edit histories, and safe serialization of edits that modify files on disk.

PATCH Request

The client must provide the base_version it is editing against. If the server-side scenario version has changed in the meantime, the request is rejected with HTTP 409 (Conflict). Only one PATCH operation may be active per scenario at a time. Concurrent edit attempts are rejected with HTTP 423 (Locked). Each successful PATCH results in a new scenario version (base_version + 1).

Changing Lane Properties
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"]
      }
    }
  ]
}

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>

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