rs-categories: add documentation for rolling stock categories and ope…

…n-data rolling stocks

Signed-off-by: Louis Greiner <[email protected]>

content/docs/explanation/models/realistic-rolling-stocks/_index.en.md

@@ -0,0 +1,63 @@
+---
+title: "Rolling stock categories"
+linkTitle: "Rolling stock categories"
+weight: 20
+description: "Defines rolling stock categories"
+---
+
+Categories are groupings of rolling stock, either by their characteristics, performance or by the nature of the services for which they have been designed or are used.
+
+The same rolling stock can be used for different types of operations and services. This versatility is reflected in the following attributes:
+- `primary_category` (required) indicates the main use of a rolling stock
+- `other_categories` (optional) indicates other possible uses of a rolling stock
+
+The primary category of a rolling stock enables several features, such as filtering, differentiated display on charts or network graphic views, and, more broadly, the aggregation of rolling stocks.
+
+An extension of this functionality at the train schedule level (`train_schedule` directly) is planned for later, made possible in particular by the other categories of rolling stock.
+
+#### Categories of rolling stocks
+
+The different default rolling stock categories are as follows:
+
+- `High-speed train` (see [High-speed train](https://en.wikipedia.org/wiki/High-speed_rail))
+- `Intercity train` (see [Intercity train](https://en.wikipedia.org/wiki/Inter-city_rail))
+- `Regional train` (see [Regional train](https://en.wikipedia.org/wiki/Regional_rail))
+- `Commuter train` (see [Commuter train](https://en.wikipedia.org/wiki/Commuter_rail))
+- `Freight train` (see [Freight train](https://en.wikipedia.org/wiki/Rail_freight_transport))
+- `Fast freight train` (which is generally lighter and faster than the above Freight train)
+- `Night train` (see [Night train](https://en.wikipedia.org/wiki/Sleeping_car))
+- `Tram-train` (see [Tram-train](https://en.wikipedia.org/wiki/Tram-train))
+- `Touristic train` (see [Touristic train](https://en.wikipedia.org/wiki/Heritage_railway))
+- `Work train` (see [Work train](https://en.wikipedia.org/wiki/Work_train))
+
+It is also planned that, in the future, a user will be able to create new rolling stock categories directly.
+
+### Realistic open data rolling stocks
+
+To make the application more accessible to users outside the railway industry, such as external contributors and research laboratories, and to prepare for the release of the public playground version of OSRD, several "imaginary" rolling stocks are available to all users.
+
+These rolling stocks are designed to cover most simulation scenarios that users may encounter.
+
+These rolling stocks are not real, due to confidentiality reasons, but they are have been created based on real data to ensure a high level of realism.
+
+The rolling stocks are provided as [JSON files](https://github.com/OpenRailAssociation/osrd/tree/dev/tests/data/rolling_stocks). We created one representative rolling stock for each category listed above.
+
+The characteristics of these rolling stocks have been calculated based on the average values of real rolling stocks within each category. Additionally, most of these models are designed to be compatible across various networks: they are primarily bi-mode (supporting multiple electrical profiles and thermal operation), which is not always the case for real-world rolling stocks.
+
+An example of rolling stock, a **high-speed train**, is represented below, from the rolling stock editor of the application:
+
+![Rolling stock](high-speed-rolling-stock.fr.png)
+
+#### Open data
+
+Since these rolling stocks are fictional (yet realistic), they can be freely used in projects beyond OSRD.
+
+To access and use them in the application:
+
+- **From the open-source playground:** The rolling stocks are available by default.
+
+- **From a locally launched application:** Use the following command to automatically import the test rolling stocks into your database:
+
+```sh
+./scripts/load-railjson-rolling-stock.sh tests/data/rolling_stocks/realistic/*.json
+```

content/docs/explanation/models/realistic-rolling-stocks/_index.fr.md

@@ -0,0 +1,64 @@
+---
+title: "Catégories de matériels roulants"
+linkTitle: "Catégories de matériels roulants"
+weight: 20
+description: "Définit les catégories de matériels roulants"
+---
+
+Les catégories sont des regroupements de matériel roulant, soit par leurs caractéristiques, leurs performances ou par la nature des dessertes pour lesquelles ils ont été conçus ou sont utilisés.
+
+Un même matériel roulant peut être utilisé pour différents types de circulation, et de desserte. Ce caractère versatile est contenu dans les attributs :
+- `primary_category` (requis) indique l'utilisation principale d'un matériel roulant
+- `other_categories` (optionel) indique les autres utilisations d'un matériel roulant
+
+La catégorie principale d'un matériel roulant permet plusieurs fonctionnalités, comme le filtrage, un affichage différencié sur les graphiques ou réticulaire, et plus globalement, d'agréger des matériels roulants. 
+
+Une extension de cette fonctionnalité au niveau des circulations (`train_schedule` directement) est prévue pour plus tard, permise notamment par les autres catégories de matériel roulant.
+
+#### Catégories de matériels roulants
+
+Les différentes catégories de matériel roulant disponibles par défaut sont les suivantes :
+
+- `Train à grande vitesse` (voir [High-speed train](https://fr.wikipedia.org/wiki/Train_%C3%A0_grande_vitesse))
+- `Train interurbain` (voir [Intercity train](https://fr.wikipedia.org/wiki/InterCity))
+- `Train régional` (voir [Regional train](https://en.wikipedia.org/wiki/Regional_rail))
+- `Train suburbain` (voir [Commuter train](https://fr.wikipedia.org/wiki/Train_de_banlieue))
+- `Train de fret` (voir [Freight train](https://fr.wikipedia.org/wiki/Train_de_fret))
+- `Train de fret rapide` (qui est généralement plus léger et rapide que le train de fret ci-dessus)
+- `Train de nuit` (voir [Night train](https://fr.wikipedia.org/wiki/Train_de_nuit))
+- `Tram-train` (voir [Tram-train](https://fr.wikipedia.org/wiki/Tram-train))
+- `Train touristique` (voir [Touristic train](https://fr.wikipedia.org/wiki/Chemin_de_fer_touristique))
+- `Train de travaux` (voir [Work train](https://fr.wikipedia.org/wiki/Train_de_travaux))
+
+Il est aussi prévu que, plus tard, un utilisateur puisse créer directement de nouvelles catégories de matériel roulant.
+
+### Matériels roulants réalistes open data
+
+Afin de rendre l’application plus accessible aux utilisateurs en dehors de l’industrie ferroviaire, tels que des contributeurs externes et des laboratoires de recherche, et de préparer la sortie de la version publique "bac à sable" d'OSRD, plusieurs matériels roulants "imaginaires" sont disponibles pour tous les utilisateurs.
+
+Ces matériels roulants ont été conçus pour couvrir la majorité des scénarios de simulation que les utilisateurs pourraient rencontrer.
+
+Ces matériels roulants ne sont pas des matériels roulants existant réellement en raison de la confidentialité des données, mais ils s’en inspirent pour garantir le réalisme des simulations.
+
+Ces matériels roulants sont fournis sous forme de [fichiers JSON](https://github.com/OpenRailAssociation/osrd/tree/dev/tests/data/rolling_stocks). Nous avons créé un matériel roulant représentatif de chaque catégorie présentée ci-dessus.
+
+Les caractéristiques de ces matériels roulants ont été calculées à partir des valeurs moyennes des matériels roulants réels de chaque catégorie. De plus, la plupart de ces modèles ont été conçus pour être compatibles avec divers réseaux : ils sont principalement bimodes (supportant plusieurs profils électriques ainsi que le fonctionnement thermique), ce qui n’est pas toujours le cas des matériels roulants réels.
+
+Un exemple de matériel roulant, un **train à grande vitesse**, est représenté ci-dessous, depuis l'éditeur de matériel roulant de l'application :
+
+![Matériel roulant](high-speed-rolling-stock.fr.png)
+
+#### Open data
+
+Puisque ces matériels roulants sont fictifs (mais réalistes), ils peuvent être librement utilisés dans des projets en dehors d’OSRD.
+
+Pour y avoir accès et les utiliser dans l'application :
+
+- **Depuis l'application open-source "bac à sable" :** Les matériels roulants sont disponibles par défaut.
+
+- **Depuis une application lancée localement :** Utilisez la commande suivante pour importer automatiquement les matériels roulants de test dans votre base de données :
+
+```sh
+./scripts/load-railjson-rolling-stock.sh tests/data/rolling_stocks/realistic/*.json
+```
+

content/docs/explanation/running_time_calculation/_index.en.md

@@ -25,7 +25,7 @@ A running time calculation is based on 5 inputs:
 
 - **The rolling stock:** The characteristics of which needed to perform the simulation are shown below.
 
-![Rolling Stock Material](mat_roulant.png)
+![Rolling Stock Material](../models/realistic-rolling-stocks/high-speed-rolling-stock.en.png)
 
 > The orange curve, called the effort-speed curve, represents the maximum motor effort as a function of the speed of travel.
 >

content/docs/explanation/running_time_calculation/_index.fr.md

@@ -25,7 +25,7 @@ Un calcul de marche est basé sur 5 entrées :
 
 - **Le matériel roulant :** Dont les caractéristiques nécessaires pour effectuer la simulation sont représentées ci-dessous.
 
-![Matériel roulant](mat_roulant.png)
+![Matériel roulant](../models/realistic-rolling-stocks/high-speed-rolling-stock.fr.png)
 
 > La courbe orange, appelée courbe effort-vitesse du matériel, représente l'effort moteur maximal en fonction de la
 > vitesse de circulation.