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

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

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

Acceptance criteria

• 7536

  • [x] NGE is customizable according to OSRD needs (can run without back-end)
  • [x] Only NGE workspace is displayed (not the project management and authentication menus)
  • [x] osrd-nge is available as npm package
  • [x] A test iframe proves the communication between osrd-nge and NGE

• 7537

  • [x] osrd-nge runs in operational studies panel
  • [x] Microscopic / Macroscopic switch works
  • [x] NGE is displayed in operational studies panel when Macroscopic switch is ticked
  • [x] Microscopic switch switches back to simulation view

• 7538

  • [x] The infrastructure (stations/nodes) involved in a scenario is displayed in NGE
  • [x] 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

• 7539

  • [x] A timetable change implies an update of the NGE model
  • [x] 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)
  • [x] Delete trainrun
    • [x] 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

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

Definition of ready

• UX

  • [x] A wireframe is ready
  • [x] A mock-up is ready

• PO

  • [x] Acceptance criteria are clear and understandable

• Technical

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

• General

  • [x] WSJF values are filled
  • [x] 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!