NRF SDK 0.9Lire et agir
Comprendre les positions et la topologie
Relier une position à sa voie, convertir les distances et traiter les réseaux partiels sans inventer de chemin.
Une voie, une fraction et un sens
Après game.snapshot(), utilisez observation.track(id) et platform(id) pour les jointures déjà indexées. Pour consulter souvent les nœuds ou métriques de voie, construisez une fois vos index depuis nodes et trackMetrics du même lot. Une Position porte trackId, fraction et direction. La fraction va de 0 à 1 depuis l’origine de la voie ; le sens +1 ou −1 indique comment on la parcourt et ne change pas cette origine.
package wiki.trackpositions
import fr.nimby.sdk.Observation
import fr.nimby.sdk.Position
import fr.nimby.sdk.TrackDirection
import fr.nimby.sdk.TrackId
class TrackPositions(snapshot: Observation) {
private val metrics = snapshot.trackMetrics?.associateBy { it.trackId }
fun atMetres(track: TrackId, offsetM: Double, direction: TrackDirection): Position? {
val metric = metrics?.get(track.value) ?: return null
if (!offsetM.isFinite() || offsetM !in 0.0..metric.lengthM) return null
return metric.positionAtMetres(offsetM, direction)
}
}
Créez TrackPositions avec l’Observation obtenue, puis appelez atMetres pour les voies souhaitées. Cette fonction d’exemple retourne null si la métrique manque ou si la distance dépasse la voie ; elle évite une recherche linéaire à chaque position. Renouvelez cet index lorsque vous adoptez une nouvelle capture.
| Conversion | Contrat |
|---|---|
| metric.offsetM(fraction) | Distance depuis l’origine, avec fraction finie dans [0, 1]. |
| metric.fraction(offsetM) | Distance finie comprise entre 0 et lengthM ; aucune extrapolation. |
| metric.distanceM(a, b) | Distance positive sur cette même voie, sans choix d’itinéraire. |
| metric.positionAtMetres(m, direction) | Position calculée localement ; ce résultat n’autorise pas une construction. |
Traiter les relations manquantes
Une capture peut ne pas fournir toutes les relations. Un lien de nœud absent ne prouve pas la présence d’un butoir. Un aiguillage décrit des connexions et des directions, pas un itinéraire réservé pour un train. Les parcours doivent détecter cycles, branches et références absentes, avec une limite de distance ou de nombre de segments.
| Donnée | Interprétation |
|---|---|
| TrackUsage | Intervalle sur une voie associé à un train. Plusieurs intervalles peuvent se chevaucher ; leur ordre ne constitue pas un chemin. |
| reservations / occupations | null : table indisponible. Une table obtenue décrit réservations et présence physique séparément. |
| selectedPath | Chemin observé du train sélectionné dans la capture complète ; ne pas le déduire des réservations triées. |
| Platform | Relie une voie de quai à une gare ; toutes les voies ne sont pas des quais. |
La capture spécialisée game.trains.snapshot ne demande pas le réseau complet. Ses tables de voies ou d’occupations ne servent donc pas à conclure que la carte est vide. Dans un outil Native, partez de context.network() et des fonctions de topologie de l’API d’outil pour éviter de réimplémenter ces parcours.