NetzGrafik-Editor (NGE) integration in OSRD

[louisgreiner]

Description

Concept diagram:

This flowchart describes how the main bricks will be communicating.

---
title: OSRD - NGE Workflow for synchronous workspaces
---
flowchart TD
  OSRD[("OSRD")] -- create / update on change --> timetable["Timetable"]
  timetable -- create / modify / delete train schedules &\n (re)calculate pathfindings and running times --> timetable
  timetable -- on change --> synchronization_timetable{"Synchro \nenabled?"}
  synchronization_timetable -- yes, save modifications ----> OSRD
  OSRD -- send infra & timetable for convertion --> converter["Converter / Event handler (osrd-front)"]
  converter -- send NGE light model \n(window.postMessage) --> NGE["osrd-nge component"]
  NGE -- create / modify / delete trainruns --> NGE
  NGE -- on change --> synchronization_nge{"Synchro \nenabled?"}
  synchronization_nge -- yes, save modifications \n(window.postMessage) --> converter
  converter -- requests to update timetable --> OSRD

Loading

As shown in the following sequence diagram, services have to develop new communcations.

---
title: OSRD - NGE Sequence diagram
---
sequenceDiagram
  autonumber
  OSRD (osrd_window)-->>OSRD (osrd_window): init web page
  OSRD (osrd_window)->>NGE (nge_iframe): set `netzgrafikDto` DOM property
  loop while synchronization is ON
    alt any modification in OSRD (osrd_window)
      OSRD (osrd_window)-->>OSRD (osrd_window): any modification
      OSRD (osrd_window)->>NGE (nge_iframe): set `netzgrafikDto` DOM property
    else any modification in NGE (nge_iframe)
      NGE (nge_iframe)-->>NGE (nge_iframe): any modification <br>(hooks)
      NGE (nge_iframe)->>OSRD (osrd_window): send `operationX` event (@Output)
      OSRD (osrd_window)-->>OSRD (osrd_window): convert NGE operation into <br/>timetable update
      OSRD (osrd_window)->>NGE (nge_iframe): set `netzgrafikDto` DOM property
    end
  end

Loading

Contacts: @louisgreiner (SNCF Réseau) - @aiAdrian (SBB CFF FFS)

Acceptance criteria

• Create osrd_nge and test project of communication with an iframe #7536
  • NGE is customizable according to OSRD needs (can run without back-end)
  • Only NGE workspace is displayed (not the project management and authentication menus)
  • osrd-nge is available as npm package
  • A test iframe proves the communication between osrd-nge and NGE
• Being able to switch between the OSRD interface and the NGE interface #7537
  • osrd-nge runs in operational studies panel
  • Microscopic / Macroscopic switch works
  • NGE is displayed in operational studies panel when Macroscopic switch is ticked
  • Microscopic switch switches back to simulation view
• [Meta] Implement a converter from OSRD scenario to NGE light model #7538
  • The infrastructure (stations/nodes) involved in a scenario is displayed in NGE
  • All the train schedules of a timetable of a scenario can be displayed in NGE
  • Running times are the same as OSRD calculations
  • Only valid trains are displayed in NGE
• Implement a converter from NGE operations to OSRD timetable update - Part 1 #7539
  • A timetable change implies an update of the NGE model
  • An action on trainruns* in NGE implies an update of the timetable
    • Create trainrun
      • Create valid trainrun with valid path => train schedule creation (simulation not working, rolling stock must be entered in OSRD first) => once the rollingstock is given and simulation done => trainrun updated (running times, same path)
      • Create valid trainrun with incomplete path (should pass by intermediary stations) => train schedule creation (simulation not working, rolling stock must be entered in OSRD first) => once the rollingstock is given and simulation done => trainrun updated (running times, updated path)
      • Create invalid trainrun => train schedule creation (simulation not working, rolling stock must be entered in OSRD first) => once the rollingstock is given and simulation failed => trainrun deleted / updated (TBD)
    • Update trainrun
      • Update trainrun path (shorten and lengthen steps or only start, intermediary or end step) => train schedule updated and simulation done => trainrun updated (updated running times, updated path)
      • Update trainrun departure time => train schedule updated and simulation done => trainrun updated (updated running times, updated path)
    • Delete trainrun
      • Delete trainrun => delete train schedule

*a trainrun in NGE is the equivalent of a train schedule in OSRD (even tho it is not semantically 100% correct)

Implementation plan

• Create osrd_nge and test project of communication with an iframe #7536
  • DevOps:
    • (Angular) Create osrd-nge: a wrapper (Angular app) that embed a build of NGE with specific settings for OSRD use (standalone mode) (see POC)
    • Build and publish osrd-nge in npm
    • Import osrd-nge from npm and make the NGE build available within OSRD build
  • Implement in NGE (with the help of Adrian):
    • (Angular) Back-end separation if standalone flag (around version-control.service.ts)
    • (Angular) eventEmitter on trainrun actions (create, update, delete) (set environment.customElement)
    • (Angular) Enable / disable NGE UI elements (authentication and project management components) to keep only workspace (netzgrafik) and filters (see Angular ngIf) (set environment.disableBackend)
  • Implement in osrd-nge:
    • event listener for OSRD data load
    • event listeners for NGE actions to be triggered on any change (callback from eventEmitter)
  • Create a test iframe project which logs all trainrun actions and has a timetable upload button using postMessages and eventListeners.
• Being able to switch between the OSRD interface and the NGE interface #7537
  • Integrate the osrd-nge iframe in operationnal studies panel and add the Microscopic / Macroscopic switch
  • OSRD (front) implements (taking inspiration of the previous work:
    • enable load of data from OSRD to NGE (template to be found in description) (OSRD->NGE)
    • event listeners for NGE actions (with empty payloads, to be filled with converter) (OSRD<-NGE)
• [Meta] Implement a converter from OSRD scenario to NGE light model #7538
  • List and confront the semantic differences and the missing data structures in OSRD (see NGE data models), taking in account TSv2
  • Enrich OSRD data structures with the least changes (to standardize the communication between services (OSRD / NGE) and no loss of informations)
  • [OSRD -> NGE] Implement converter (front): timetable => netzgrafikDto
    • Implement payload and set netzgrafikDto DOM root property
      • Import infrastructure from scenario (can be based on create_nge_model_infra method from PoC)
      • Import timetable from scenario (can be based on create_nge_model_with_trains method from PoC, taking in account TSv2)
    • Enable @Input for this message in NGE
    • Functional testing on callback function loadNetzgrafikDto
    • Unitary and functionnal tests
• Implement a converter from NGE operations to OSRD timetable update - Part 1 #7539
  • [OSRD <- NGE] Implement events handler for NGE operations (in OSRD front) => requests to update timetable
    • Enable eventListener for the NGE operationX events
    • Callback functions to update back-end (timetable)
    • Unitary and functionnal tests

Definition of ready

• UX

  • A wireframe is ready
  • A mock-up is ready

• PO

  • Acceptance criteria are clear and understandable

• Technical

  • If required documentation is available on osrd.fr
  • Implementation plan is detailed and validated by maintainers

• General

  • WSJF values are filled
  • Validated by the PM

[aiAdrian]

I will have a look into the current version of Netgrafik-Editor and try to locate the all the required changes to get the integration done.

[aiAdrian]

Excellent work!