Updated UML diagrams.

design/dem-loading-class-diagram.puml

@@ -27,7 +27,7 @@
 
   package org.orekit.rugged #ECEBD8 {
 
-    package api #DDEBD8 {
+    package raster #DDEBD8 {
       interface UpdatableTile {
         +setGeometry(φ₀, λ₀, δφ, δλ, rows, columns)
         +setElevation(i, j, h)
@@ -36,9 +36,7 @@
         +updateTile(φ, λ, UpdatableTile)
       }
       TileUpdater --> UpdatableTile : updates
-    }
 
-    package raster #DDEBD8 {
       interface "TileFactory<T extends Tile>" as TileFactory_T_ {
         +T createTile()
       }

design/direct-localization-sequence-diagram.puml

@@ -21,6 +21,7 @@
   skinparam NoteBorderColor                     #691616
   skinparam NoteFontColor                       #691616
   skinparam SequenceActorBorderColor            #6A584B
+  skinparam SequenceActorBackgroundColor        #F3EFEB/CCC9C5
   skinparam SequenceParticipantBackgroundColor  #F3EFEB/CCC9C5
   skinparam SequenceParticipantBorderColor      #6A584B
   skinparam SequenceLifeLineBackgroundColor     #CCC9C5/F3EFEB
@@ -31,7 +32,7 @@
 
   hide footbox
 
-  participant "UserMain" as A
+  actor       "UserMain" as A
   participant "Rugged" as R
   participant "LineSensor" as LS
   participant "SpacecraftToObservedBody" as S

design/geometry-at-date-sequence-diagram.puml → design/duvenhage-inner-recursion-activity-diagram.puml

@@ -20,34 +20,50 @@
   skinparam NoteBackgroundColor                 #F3EFEB
   skinparam NoteBorderColor                     #691616
   skinparam NoteFontColor                       #691616
-  skinparam SequenceActorBorderColor            #6A584B
-  skinparam SequenceParticipantBackgroundColor  #F3EFEB/CCC9C5
-  skinparam SequenceParticipantBorderColor      #6A584B
-  skinparam SequenceLifeLineBackgroundColor     #CCC9C5/F3EFEB
-  skinparam SequenceLifeLineBorderColor         #6A584B
-  skinparam SequenceArrowColor                  #6A584B
-  skinparam SequenceBorderColor                 #6A584B
-  skinparam SequenceFontSize                    11
+  skinparam ActivityStartColor                  #6A584B
+  skinparam ActivityEndColor                    #6A584B
+  skinparam ActivityBarColor                    #6A584B
+  skinparam ActivityBorderColor                 #691616
+  skinparam ActivityBackgroundColor             #F3EFEB/CCC9C5
+  skinparam ActivityArrowColor                  #691616
+  skinparam ActivityFontSize                    11
 
-  hide footbox
-
-  participant "Caller" as C
-  participant "Rugged" as R
-  participant "Orekit" as O
-
-  activate C
-  C -> R : compute geometry at date
-    activate R
-    R -> O : interpolate(date)
-      activate O
-      O --> R : orbite/attitude
-      deactivate O
-    R -> O : getTransform(date)
-      activate O
-      O --> R : Earth to inertial transform
-      deactivate O
-    R --> C : spacecraft to inertial, inertial to Earth
-    deactivate R
-  deactivate C
+  start
+  if (recursion depth > 30) then (yes)
+    : search failed;
+    stop
+  endif
+  if (start and end point on same pixel) then (yes)
+    : return pixel intersection;
+    stop
+  endif
+  : compute kd-tree deepest level\ncontaining both start and end points;
+  if (compare segment and sub-tile maximum elevation) then (fully above)
+    : return null;
+    note right
+      when the line-of-sight segment is fully above
+      Digital Elevation Model, we can safely reject
+      it and proceed to next segment
+    end note
+    stop
+  endif
+  :previous ← start;
+  : crossings ← line-of-sight segment crossings of next level sub-tiles;
+  note right
+    crossings can be computed either
+    using flat body hypothesis
+    or taking curvature into account
+  end note
+  repeat
+    :intersection ← recurse(previous, crossing);
+    if (found intersection?) then (yes)
+      : return intersection;
+      stop
+    endif
+    :previous ← crossing;
+  repeat while (more crossings?)
+  :intersection ← recurse(previous, end);
+  : return intersection;
+  stop
 
 @enduml

design/duvenhage-top-loop-activity-diagram.puml

+' Copyright 2013-2014 CS Systèmes d'Information
+' Licensed to CS Systèmes d'Information (CS) under one or more
+' contributor license agreements.  See the NOTICE file distributed with
+' this work for additional information regarding copyright ownership.
+' CS licenses this file to You under the Apache License, Version 2.0
+' (the "License"); you may not use this file except in compliance with
+' the License.  You may obtain a copy of the License at
+'
+'   http://www.apache.org/licenses/LICENSE-2.0
+'
+' Unless required by applicable law or agreed to in writing, software
+' distributed under the License is distributed on an "AS IS" BASIS,
+' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+' See the License for the specific language governing permissions and
+' limitations under the License.
+
+@startuml
+
+  skinparam svek                                true
+  skinparam NoteBackgroundColor                 #F3EFEB
+  skinparam NoteBorderColor                     #691616
+  skinparam NoteFontColor                       #691616
+  skinparam ActivityStartColor                  #6A584B
+  skinparam ActivityEndColor                    #6A584B
+  skinparam ActivityBarColor                    #6A584B
+  skinparam ActivityBorderColor                 #691616
+  skinparam ActivityBackgroundColor             #F3EFEB/CCC9C5
+  skinparam ActivityArrowColor                  #691616
+  skinparam ActivityFontSize                    11
+
+  start
+  : gp₀ ← point at altitude 0;
+  : select tile containing gp₀;
+  : current point ← null;
+  : hmax ← tile maximum elevation;
+  while (current point is null)
+    : entry ← point at altitude hmax;
+    if (locate entry point) then (in selected tile)
+    else (outside of selected tile)
+      : select tile containing entry point;
+      : hmax ← max(hmax, tile maximum elevation);
+      : current point ← null;
+    endif
+  endwhile
+  repeat
+    : exit ← line-of-sight exit point from tile;
+    : intersection ← Duvenhage(current, exit);
+    if (found intersection?) then (yes)
+      : return intersection;
+      stop
+    endif
+    if (tile exited at side?) then (no)
+      : searching ← false;
+    else (yes)
+      : forward point ← point slightly after exit point;
+      : select tile containing forward point;
+      if (DEM traversed between\ncurrent and forward points) then (yes)
+        : return current point;
+        note right
+         extremely rare case!
+        end note
+        stop
+      endif
+      : current point ← forward point;
+    endif
+  repeat while (searching ?)
+  :search failed;
+  note left
+    this should never happen
+  end note
+
+@enduml

design/configuration-class-diagram.puml → design/initialization-class-diagram.puml

@@ -27,11 +27,23 @@
 
   package orekit #ECEBD8 {
     class OneAxisEllipsoid
-    class Frame
     class PVCoordinatesProvider
+    class Frame
     class AttitudeProvider
   }
 
+  package mission.specific #C4D2C5 {
+    class UserMain #D5E0D5/E2EBE2
+    note top #E2EBE2
+      user configures Rugged either by
+      selecting from a few predefined
+      choices or by directly building
+      Orekit objects
+    end note
+    class MissionSpecificDEM #D5E0D5/E2EBE2
+    MissionSpecificDEM <-left- UserMain : creates
+  }
+
   package rugged #ECEBD8 {
 
     package utils #DDEBD8 {
@@ -46,7 +58,16 @@
 
     }
 
+    package raster #DDEBD8 {
+      interface TileUpdater
+    }
+
     package api #DDEBD8 {
+      class Rugged {
+        +setLightTimeCorrection(boolean)
+        +setAberrationOfLightCorrection(boolean)
+        +addLineSensor(lineSensor)
+      }
       enum AlgorithmId {
         +DUVENHAGE
         +DUVENHAGE_FLAT_BODY
@@ -71,33 +92,21 @@
         +TOD
         +VEIS1950
       }
-      class Rugged {
-        +setLightTimeCorrection(boolean)
-        +setAberrationOfLightCorrection(boolean)
-        +addLineSensor(lineSensor)
-      }
       class LineSensor
       ExtendedEllipsoid        "1" <--o Rugged
       SpacecraftToObservedBody "1" <--o Rugged
       Rugged o--> "*" LineSensor 
-    }
+      Rugged --> AlgorithmId
+      Rugged --> EllipsoidId
+      Rugged --> BodyRotatingFrameId
+      Rugged --> InertialFrameId
 
-  }
+      UserMain    -->  LineSensor  : creates
+      MissionSpecificDEM --|> TileUpdater
+      UserMain    -->  Rugged      : configures
+
+    }
 
-  package mission.specific #C4D2C5 {
-    class UserMain #D5E0D5/E2EBE2
-    AlgorithmId         <-- UserMain : selects
-    EllipsoidId         <-- UserMain : selects
-    BodyRotatingFrameId <-- UserMain : selects
-    InertialFrameId     <-- UserMain : selects
-    LineSensor          <-- UserMain : creates
-    Rugged              <-- UserMain : configures
-    note as N1 #E2EBE2
-      user configures Rugged either by
-      selecting from a few predefined
-      choices or by directly building
-      Orekit objects
-    end note
   }
 
 @enduml

design/initialization-sequence-diagram.puml

@@ -21,6 +21,7 @@
   skinparam NoteBorderColor                     #691616
   skinparam NoteFontColor                       #691616
   skinparam SequenceActorBorderColor            #6A584B
+  skinparam SequenceActorBackgroundColor        #F3EFEB/CCC9C5
   skinparam SequenceParticipantBackgroundColor  #F3EFEB/CCC9C5
   skinparam SequenceParticipantBorderColor      #6A584B
   skinparam SequenceLifeLineBackgroundColor     #CCC9C5/F3EFEB
@@ -31,41 +32,53 @@
 
   hide footbox
 
-  participant "Application" as A
-  participant "Interface" as I
+  actor       "UserMain" as A
+  participant "MissionSpecificDEM" as B
   participant "Rugged" as R
+  participant "ExtendedEllipsoid" as E
+  participant "SpacecraftToObservedBody" as S
+  participant "LineSensor" as LS
   participant "Orekit" as O
 
   activate A
-    A -> I : init
-    activate I
-      I -> I : loadModels
-      I -> I : unfoldOpticalPath
-      activate I
-      deactivate I
-      I -> R : setGeneralContext(algorithm, frames, ellipsoid, ephemeris)
-      activate R
-        R -> O : createInterpolator(ephemeris)
-        activate O
-          O --> R : interpolating propagator
-        deactivate O
-        R -> R : createTransformProvider(interpolator)
-        activate R
-         deactivate R
-      deactivate R
-      I -> R : setLineSensor(sensorName, pixels, datationModel)
-      activate R
-      deactivate R
-      I -> R : setLineSensor(sensorName, pixels, datationModel)
-      activate R
-      deactivate R
-      I -> R : setLineSensor(sensorName, pixels, datationModel)
-      activate R
-      deactivate R
-      I -> R : setUpTilesManagement(tileUpdater, maxCachedTiles)
-      activate R
-      deactivate R
-    deactivate I
+    A -> A : loadModels
+    A -> B : create
+    activate B
+    deactivate B
+    A -> A : unfoldOpticalPath
+    activate A
+    deactivate A
+    A -> R : create(DEM, algorithm, frames, ellipsoid, ephemeris)
+    activate R
+      R -> E : create
+      activate E
+      deactivate E
+      R -> O : createProviders(ephemeris)
+      activate O
+        O --> R : position/velocity/atttitude providers
+      deactivate O
+      R -> S : create
+      activate S
+      deactivate S
+    deactivate R
+    A -> LS : create
+    activate LS
+    deactivate LS
+    A -> R : addLineSensor
+    activate R
+    deactivate R
+    A -> LS : create
+    activate LS
+    deactivate LS
+    A -> R : addLineSensor
+    activate R
+    deactivate R
+    A -> LS : create
+    activate LS
+    deactivate LS
+    A -> R : addLineSensor
+    activate R
+    deactivate R
   deactivate A
 
 @enduml

design/inverse-localization-sequence-diagram.puml

@@ -21,6 +21,7 @@
   skinparam NoteBorderColor                     #691616
   skinparam NoteFontColor                       #691616
   skinparam SequenceActorBorderColor            #6A584B
+  skinparam SequenceActorBackgroundColor        #F3EFEB/CCC9C5
   skinparam SequenceParticipantBackgroundColor  #F3EFEB/CCC9C5
   skinparam SequenceParticipantBorderColor      #6A584B
   skinparam SequenceLifeLineBackgroundColor     #CCC9C5/F3EFEB
@@ -31,57 +32,66 @@
 
   hide footbox
 
-  participant "Application" as A
-  participant "Interface" as I
+  actor       "UserMain" as A
   participant "Rugged" as R
-  participant "Orekit" as O
+  participant "SensorMeanPlaneCrossing" as P
+  participant "SensorPixelCrossing" as X
+  participant "SpacecraftToObservedBody" as S
+  participant "ExtendedEllipsoid" as E
+  participant "Transform" as T
   participant "Math" as M
 
   activate A
-  A  -> I : inverseLocalization(φ, λ)
-     activate I
-       I  -> R : inverseLocalization(φ, λ)
-       activate R
-         R  -> R : elevation(φ, λ)
-         activate R
-            R -> I : DEM callback
-            I --> R : DEM raw data cell
-            R --> R : h(φ, λ)
-         deactivate R
-         R -> O : convert(ellipsoid, φ, λ, h)
-         activate O
-           O --> R : P(φ, λ, h) in Earth frame
-         deactivate O
-         R -> R : createSwathOffset(P, interpolator)
-         activate R
-           R --> R : function f(t)
-         deactivate R
-         R -> M : solve f(t₀) = 0
-         activate M
-           M --> R : evaluate f(t)
-           activate R
-             R -> R : apply combined transform provider at date
-             R --> M : f(t)
-           deactivate R
-           M --> R : evaluate f(t)
-           activate R
-             R -> R : apply combined transform provider at date
-             R --> M : f(t)
-           deactivate R
-           M --> R : evaluate f(t)
-           activate R
-             R -> R : apply combined transform provider at date
-             R --> M : f(t)
-           deactivate R
-           M --> R : t₀
-         deactivate M
-         R -> R : apply combined transform provider at date
-          R -> R : apply inverse time stamping model
-          R -> R : locate pixel in line for solved geometry
-          R --> I : pixel coordinates
-       deactivate R
-        I --> A : pixel coordinates
-    deactivate I         
+    A  -> R : inverseLocalization
+    activate R
+      R  -> P : getMeanPlaneFinder
+      activate P
+        P -> S : getTransform(each line)
+        note left
+           transforms are computed
+           only once and reused
+           across successive inverse
+           localization calls
+        end note
+        activate S
+          S -> T : create
+          activate T
+          deactivate T
+        deactivate S
+      deactivate P
+      R -> E : transform(φ, λ, h)
+      activate E
+        E --> R : x, y, z
+      deactivate E
+      R -> P : findCrossing(ground target)
+      activate P
+        P -> T : interpolate
+        activate T
+        deactivate T
+        note left
+           algorithm converges
+           in 2 or 3 iterations
+        end note
+        P -> T : interpolate
+        activate T
+        deactivate T
+        P --> R : target direction at mean plane crossing\n(with time derivative)
+      deactivate P
+      R -> X : create(target direction at crossing time)
+      activate X
+      deactivate X
+      R -> X : locatePixel
+      activate X
+        X -> M : solve f(x) = 0
+        activate M
+          M --> X : x₀
+        deactivate M
+        X --> R : coarse pixel crossing
+      deactivate X
+      R -> R : fix line, considering closest pixel position
+      R -> R : fix pixel
+      R --> A : accurate line/pixel
+    deactivate R
   deactivate A
 
 @enduml