Apogy/Concepts

Overview

In Apogy, users control Systems by invoking commands (through Programs) and monitor the System's health through telemetry (i.e. states).

These Systems are operated in a Environment which defines such things as Digital Elevation Maps, orbit models, sun position, etc (i.e. what the Environment contains).

User, System, Environment and Data Product.

The System's command produces result (i.e. returned value, such as an Image, an error code, etc.) that Apogy geo and time tags. This allows the results to be displayed within the 3D Environment. This helps in maintaining the situational awareness of the operator and keep the data in context.

Session

In Apogy, the Session is the entity that contains all the configuration and data that are required to make use of Systems. The session is implemented as an Eclipse Project with an Apogy nature, and as such, is mapped to the host file system. Sessions can be exported/imported to and from archived files (.zip).

The Session project includes a central resource (session.sym) that contains most of the configuration elements (Variable, Context, InitialCondition, etc) and also has references to other ressources contained in the project (scripts, data products, etc). In Apogy there is at most one active Session at any given time.

The Session contains:

1. the Environment being used;
2. the list of Programs that can be executed;
3. the list of available InitialConditions;
4. the list of Tools that are available.

Systems

In Apogy, a System is an entity that can execute commands and provide its state information. Typically Systems represent actual hardware (ex: a rover, a camera, a robotic arm) but can be used to represent something more abstract (a planning system, a resource dispatcher, etc.).

In Apogy, a user makes use of the Systems to perform tasks in a given Environment. The System supports commands and reports on it status through its telemetry : the System is defined by its interfaces. Given this definition, a System can be modeled as a class : methods represent commands (with their parameters and return value) and the attributes represent states returned as part of telemetry. In Apogy, a System is defined using the Eclipse Modeling Framework.

In Apogy a System is named and is defined in EMF model. This model includes:

1. The System Interface Class defining the commands and attributes it supports;
2. A list of Connection Points where other sub-system can be attached;
3. A list of Assembly Links that are used to assemble a System's sub-System (in composite Systems);
4. A topology of nodes that are used to defined the system representation in 3D;
5. A list of Topology Bindings that are used to bind attributes of the interface class to behavior in the topology (ex: binding the value of a 3D transform to the value of a revolute joint position);

Simple Systems can be assembled together to create composites Systems (ex: Integrated Rover Example). This allows sub-systems to be modeled independently and reused as part of different assemblies. The assemblies of Systems is supported through System Type Members, Connection Points and Assembly Links.

System Interface Class

The System's Interface Class refers to the EClass that defined the 'Operations' (methods) and attributes of the System. Only Operation and attributes defined in the interface can be accessed by Apogy to create commands, display values, bind attributes, etc.

System Type Members

Composite System contains Type Members that refers to other System. This is the pattern used by Apogy to implement composite data type (ex: struct in C programming language ). These Type Members can be made accessible to the parent System.

An example of a composite System and its Type Members. In this example, type member platform is of type MobilePlatform.

Apogy allows operations to be called on a composite System's Type Member (ex: calling rover→mobilePlateform.moveForward(1.25)) in a hierarchical fashion. In the same way, attributes of sub-system can be accessed (rover→mobilePlateform.leftWheelPosition).

System can be compose at multiple levels (i.e. a System can have type members that are themselves composites Systems and so on.). The Integrated Rover is an example of such a System.

Connection Points

Connection Points define physical locations where other sys-system are expected to be connected. To used the analogy of a construction toy's blocks, connections point points define the brick studs.

A System connection points and relationship to the System's topology. The connection points are shown as yellow rectangles and topology Nodes as blue rounded rectangles.

They are named and refer to a Node defined in the System's topology. The root connection point is implicit and always refer to the System's root topology node.

Assembly Links

Assembly Links describe how systems are attached to each other in composite Systems.

A composite system assembly using connection points (yellow rectangles) and assembly links (black arrows). The IntegratedRoboticArm sub-system is attached to the Front Connection Point located on the MobilePlateform, while the Camera1 sub-system is connected to the Top connection point.

In the construction toy's analogy, the assembly links represent a construction set's instructions. The assembly links are named and refers to their parent's connection point to which the subsystem root connection point is attached.

Variable

A user can define multiple instances for a given System (ex: vehicle1 and vehicle2 of type MobilePlateformApogySystem). Similar to the way multiple variables of a given type can be defined in programming languages, Apogy uses the concept of Variable.

Each Variable has a name (that should be unique) and refers to the type of System it represents. Variable can refer to simple or complex System.

Context

When developing complex operations sequence or testing scripts that command Systems to perform tasks, a user often needs to run such commands on some sort of simulated version of the Systems. In other cases, during development, a specific sub-system of a larger assembly may not yet have an implementation that communicates with it's hardware (or the hardware may not yet be available). A way for the user to work on operational sequence or scripts should be made available. In summary, the specific System implementation used typically depends on the context of use.

In order to addresses such cases, Apogy makes use of Context . At it's base, a Context maps Variable to actual implementations of the Interface Class of its System and sub-systems. By doing so, when a Variable is instanciated, the actual Interface Class Implementation specified in the Context is used. Used together with a System Interface sub-classes, the Context allows commands and script to be executed in a transparent fashion in diverse implementation settings.

Simulated Context selected as the active context.	Real Context selected as the active context.

In the example above, 3 Variable have been defined:

1. myRover : Refers to a System which Interface Class is Rover, which has 2 sub-classes:
   1. RoverSimulated : A simulated implementation of the Rover;
   2. RoverReal : An implementation that connects to the actual hardware rover.
2. myArm : Refers to a System which Interface Class is Arm, which has 2 sub-classes:
   1. ArmSimulated : A simulated implementation of the Arm;
   2. ArmReal : An implementation that connects to the actual hardware robot.
3. myLidar : Refers to a System which Interface Class is Lidar. In this cas, the Lidar hardware being no yet completed, only 1 sub-class is available:
   1. LidarSimulated : A simulated implementation of the Lidar;

The user has created 2 Context : Simulated and Real. In this case, both real and simulated version of the rover and arm are used, but the Lidar hardware not being available, both Context make use of the simulated implementation (LidarSimulated) of the Lidar. This setup allows command sequence or scripts to be developed and tested now using the Simulated context, and later used with the real world implementation when the actual Systems become available.

While many Context can be defined in a given Session, only one can be selected as the active context. The Context definition includes:

1. A name (should be unique);
2. The DataSet where results will be stored. This allows result from different Context to be saved separately (this is often useful to keep data from a simulated run separate from data produced by actual, real System).

Environment

The Environment contains the definitions of worksite, and what the user has to work with in a specific mission (such as Variables, Context, Worksite, etc).

The Environment contains the following:

1. the Variables that are available;
2. the list of available Contexts and the one currently active;
3. the list of available Worksite and the one currently active;
4. the list of available Time Source and the one currently active;

Time Source

Time Sources are used to feed the time to the Session. This in turns updates the position of the sky elements (Sun, Moon, Stars).

Apogy provides the following Time Sources:

Type	Description
Fixed Time Source	A time source representing a fixed date and time.
Current Time Source	A time source that represent the current time, updated a regular interval.
Selection based Time Source	A time source that updates its time upon selection of any Timed element in the UI.
Browseable Time Source	A time source that can browsed, reset, play forward or reverse and accelerated.

Worksite

A Worksite represent the physical surroundings where the Systems are being used.

While many Worksite can be defined in a given Environment, only one is active at any given time .

A Worksite contains:

• A name
• A description
• A Sky which contains a Sun and a StarField

Apogy provides a few specialization of Worksite for different places. The appearance of these specialized worksites will differ when viewed in the 3D Viewer.

Sun

The Sun is represented in the Sky in Apogy. Its position in the Sky is updated based on the current active TimeSource used and thy location of the Worksite. One attribute of the Sun radius is its radius : this is used to compute the apparent angular diameter of the Sun in the Sky in the 3D viewer. The Sun also provide a method used to get its irradiance given a distance.

The Sun is a Node in the topology, thus its position relative to other Node can be queried.

Moon

The Moon is represented in the Sky in Apogy (when applicable for the Worksite). Its position in the Sky is updated based on the current active TimeSource used and thy location of the Worksite. One attribute of the Moonradius is its radius : this is used to compute the apparent angular diameter of the Moon in the Sky in the 3D viewer.

The Moon is a Node in the topology, thus its position relative to other Node can be queried. An example of such use if found in the # PTUDishAntennaApogySystem.

Star Field

The Star Field contains the stars that are seen in the Sky. The Star Field contains a list of Stars . The Star Field contains all the stars found the Bright Star Catalog, which includes more than 9000 stars.

Each Star includes:

• Apparent magnitude which defines how bright the star appears;
• Equatorial Coordinates that locates it on the celestial sphere;

The number of star shown in the Sky can be changed by configuring the cut-off magnitude in the 3D Viewer preferences.

Surface Worksite

A Surface Worksite is a specialization of Worksite and represent a worksite located at the surface of a celestial body. It contains a list of Map, which are component of a Worksite that contains Map Layers that are sharing a common pose relative to the Worksite origin.

Map

In Apogy, a Map contains MapLayers that shared a common position and orientation relative to a Surface Worksite origin. If we use the analogy of an atlas, a Map represent a given region (like a page in the atlas), and the map can contain multiple layers (roads, waterway, topography).

Surface Worksite, Maps and MapLayers. Here 3 layers have been defined : A CartesianMeshLayer contains a Digital Elevation Map representing the topography of the terrain An ImageLayer shows satellite imagery of the region A DiscreteSlopeImageLayer shows the slope of the terrain as a colored coded image.

Map Layer

A map layer represent data of a given nature for a given Map.

Cartesian Triangular Mesh Layer

A Cartesian Triangular Mesh Layer contains a triangular mesh that represents surface topography.

Apogy currently supports the following Cartesian Triangular Mesh Layer:

Type	Description	Example
CartesianTriangularMeshURLMapLayer	A layer that contains a mesh and uses URL to locate the mesh data.

Image Layer

In Image Layer contains an image and its associated size when projected onto the Worksite. Apogy currently supports a variety of Image Layers:

Type	Description	Example
URLImageMapLayer	A layer that represent aerial imagery and uses a URL to locate the image data. The example shows the Canadian Space Agency Emulation Terrain seen from above. Resolution is 0.26 m/pixel.
CartesianTriangularMeshHeightImageLayer	A layer that generates a color codded height associated with a mesh. The example shows the Canadian Space Agency Emulation Terrain elevation. Resolution is 0.5 m/pixel.
CartesianTriangularMeshSlopeImageLayer	A layer that generates a color codded slope image associated with a mesh. The example shows the Canadian Space Agency Emulation Terrain slope. Resolution is 0.5 m/pixel, slopes color is scaled from 0° to 20°.
CartesianTriangularMeshDiscreteSlopeImageLayer	A layer that generates a color codded slope image with discrete slope interval. The example shows the Canadian Space Agency Emulation Terrain discrete slope. Resolution is 0.5 m/pixel, slope ranges are 0° to 10 ° green, 10° to 20° (yellow), 20° to 90° (red).
FixedPositionLineOfSightImageLayer	A layer that generates an image showing whether or not line of sight is present between a point at a certain height above a mesh and a specified fixed location. The example shows the Canadian Space Agency Emulation Terrain line of sight. Resolution is 0.5 m/pixel, the observer located at (0,0,2) (lower right corner of the image, 2 meters above ground) for points 1.0 meter above the surface.
TopologyTreeMapLayer	A layer that can be used to add a arbitrary topology tree onto a Worksite.

Once defined, Image Layer can be projected onto Cartesian Triangular Mesh Layer through the use of Layer Presentation. Layer Presentation provides control over how the image are to be projected (transparency) and order of projections:

The Canadian Space Agency Emulation Terrain topography with aerial imagery and discrete slopes superimposed on the topography.

Image Layer Presentation

TODO

Feature Of Interest

TODO

Feature Of Interest Layer

TODO

Earth Surface Worksite

This is a specialization of # Surface Worksite for working on the surface of the Earth. The Earth Surface Worksite includes the following:

• The Geographical Coordinates (longitude, latitude and altitude) of its origin;
• The angle (XAxisAzimuth) between is X axis and true North.
• An Earth Sky which includes:
  • the Sun
  • the Moon
  • the stars (a StarField)

The position of the Sun, the Moon and the stars are dynamically updated based on the time and date provided by the active TimeSource and the location of the worksite on Earth.

The Earth Surface Worksite Frame Of Reference

The orientation of the reference frame of the Earth Surface Worksite is as follow:

The Z axis point toward zenith; The X axis points at an angle of XAxisAzimuth away from true North (angle is positive toward the East); The Y axis is oriented to form a right handed coordinates frame;

Earth Atmosphere Worksite

TODO

Earth View Configuration

An Earth View Configuration is used to by the Earth View to defined what Earth View Layers will be displayed in the view. It acts as a container of Earth View Layers. Multiple Earth View Configuration can be defined, but only one is displayed by the Earth View at any given time.

Earth View Layer

An Earth View Layer defines a element to be rendered in the Earth View . The include Earth surface features (locations, area), atmospheric volume (air traffic control area) or orbital features (orbital path, swath corridor).

Apogy defines a few generic Earth View Layers:

Name	Description
AirspaceWorldWindLayer	A layer that display a airspace volume defined by a list of geographical coordinates, a lower and an upper altitude.
EarthSurfaceLocationWorldWindLayer	A layer representing a location on the Earth.
GeographicCoordinatesPathWorldWindLayer	A layer representing a path defined as a list of Geographical Coordinates.
GeographicCoordinatesWorldWindLayer	A layer representing a list of Geographical Coordinates (not forming a path).
GroundStationWorldWindLayer	A layer representing a ground station on Earth.
KMLWorldWindLayer	A layer representing the content of a KML / KMZ file.
OrbitModelWorldWindLayer	A layer representing an orbital path as defined by an OrbitModel.
SpacecraftWorldWindLayer	A layer representing the current position of a spacecraft defined by an OrbitModel.
SpacecraftSwathWorldWindLayer	A layer representing the ground swath corridor defined for a spacecraft which orbit is defined by an OrbitModel.
SurfacePolygonWorldWindLayer	A layer representing a polygonal area on the ground that is defined by a list Geographical Coordinates.

Program Group

A Program Group is a container of Program. It is used to organize Program into groups.

Program

A Program is an entity that invokes Operation Calls on Variables. Apogy currently supports two types of Programs: Operation Call List and Java Script Program .

Operation Call List

An Operation Call List is a simple Program that contains a list of Operation Calls that are to be invoked in the order that are found in the list. There is no flow control. Individual Operation Call can be invoke through the User Interface.

Java Script Program

An Java Script Program is a JavaScript script that invokes Operation Calls when executed. Apogy provides a very basic script editor can be used to view/edit JavaScript files. Java Script files are saved in the scripts folder under the current Session project file structure.

Operation Call

An Operation Call is a specific invocation of an Operation on a Variable using a set of parameters.

It contains:

1. A reference to the Variable;
2. References to a Variable type member and/or feature onto which to call the Operation (if applicable);
3. An Operation to be called;
4. A List of Arguments to use when calling the Operation;

Data Products

TODO

Initial Conditions

Apogy defines Initial Conditions which are used to capture the current states information of all System currently in use. Initial Conditions can be applied to a Session to initialize all System to a previous configuration. This is useful when testing a Program (the user can reset the System to a know state before testing a Program).

Multiple Initial Conditions can be defined and their content updated with the current System state at any time. Note that the actual data captured and System initialization is delegated to the System API Adapter implementation provided by the System developer.

Topology

In Apogy, a topology is a tree structure of Nodes that represents the spatial organization of elements used to represent a System or a Worksite component in 3D space.

An example of topology. This is the topology associated with the PTU Camera example.

It is similar to a scene graph often found in 3D renderering environment.

Node

A Node is used to represent the content, physical properties, spatial transformation, grouping or other concepts that are required to model a System or Worksite. Each Nodes contains:

1. A unique alphanumeric ID that should be unique;
2. A reference to its parent (which is a Node);
3. A description

Apogy provides a few Node specializations (read sub-classes) that are used for various functions. The following table describes some of the Node type found the most often in the topologies of Systems and Worksites:

Node Type	Description
GroupNode	A Node that posses children.
PositionNode	A Node that provides a position transformation between its parent and its child.
RotationNode	Provides an orientation transformation between its parent and its children.
TransformNode	Provides both position and orientation transformation between its parent and its children. Its both a PositionNode and RotationNode.
URLNode	A Node that refer to a file where 3D geometry is found. This is the type of node used to associate geometry to element of a System for example.
ContentNode	A Node that expose generic data in a topology tree. This is used to insert data that is not a Node in a topology in a generic fashion.
ArbitraryViewPoint	Used to represent the position and orientation of a view point that is attached to the root of the virtual world. This is used by the 3D Viewer to position the view location in the virtual environment.
AttachedViewPoint	Used to represent the position and orientation of a view point that is attached to any GroupNode in a topology. This is used by the 3D Viewer to attach a view location to a moving node (ex: a rover, a camera, etc.) in the virtual environment.
AttachedViewPoint	Used to represent the position and orientation of a view point that is attached to any GroupNode in a topology. This is used by the 3D Viewer to attach a view location to a moving node (ex: a rover, a camera, etc.) in the virtual environment.
ResultNode	Used to represent the result of an Operation Call in a topology. It is created when a Operation Call is invoked in Apogy. By default, it is represented as a flag that displays the data and time of the Operation Call .
CircularSectorFieldOfView	Used to represent a field of view shaped like a circular sector.
ConicalFieldOfView	Used to represent a field of view shaped like a cone. Typically used to represent field of view of sonars.
RectangularFrustumFieldOfView	Used to represent a field of view shaped a viewing frustum. Typically used to represent the field of view of cameras.
AmbiantLight	A light that illuminate all objects uniformly from all directions.
DirectionalLight	A light that illuminate object along one given direction specified as a unity vector. This is the type of light used to model the Sun's and Moon's light in the 3D viewer.
PointLight	A attenuated light source located at a specified point in space and that radiate light equally in all directions from its position.
SpotLight	A attenuated light source located at a specified point in space and that radiate light in a cone centered on its z axis.
Sun	The Sun is a Node.
Moon	The Moon is a Node.
StarField	The StarFieldis a Node.

Node Presentation

A Node Presentation is used to define how a Node in a topology is rendered in the 3D Viewer. The basic Node Presentation includes:

1. A reference to the Node it is associated to;
2. A visibility flag specifying if the Node (and its children) should be rendered or not.
3. A color used for rendering. Note that the 3D rendering of some Node do not use this attribute (ex: TransformNode).
4. A boolean flag specifying whether or not the ID of the associated Node should be shown.
5. A boolean flag specifying whether or not the Node rendering should be shown as selected.
6. A boolean flag specifying whether or not the Node should be included in the calculation used for determining the 3D environment boundaries (use in the Zoom fit command of the viewer).

The Node Presentation concept has been specialized for some Node type to include additional rendering attributes.

Node Presentation Registry

The Node Presentation Registry is a central list of all the Node Presentation that are associated with the Nodes currently part of the topology. It provides functions to resolve the Node Presentation for given Node and manage the life cycle of Node Presentation.

Topology Bindings

Topology Bindings are what Apogy uses to associates behavior to Nodes in the topology.

Most of the Topology Bindings used in Apogy relate selected System Interface Class attributes to behaviors of the topology. These binding allows the topology or attributes of the Nodes in a topology to be modified as a result of changes in a System's attribute.

Such Topology Bindings could be used, for example:

• Bind the position of a specified TransformNode to a linear position attribute in a System Interface Class;
• Bind a vertical and horizontal angles of a RectangularFrustmFieldOfView in the topology to the FOV attribute of a camera in a System Interface Class ;

Apogy provides a few Topology Bindings specializations (read sub-classes) that are used for various functions. The following table describes some of the Topology Bindings type found the most often in the topologies of Systems:

Type	Description
RotationBinding	A binding that maps a numerical value attribute of a System to a rotation about one axis of a specified RotationNode.
TranslationBinding	A binding that maps a numerical value attribute of a System to a translation along one axis of a specified PositionNode.
TransformMatricBinding	A binding that maps a 4x4 transform matrix value attribute of a System to a the 6 DOF transform of a TransformNode.
BooleanBinding	A binding that maps a boolean value attribute of a System to a two different topology to be attached to a specified GroupNode. If the attribute is true, one topology is attached under the specified GroupNode, if the value is false, a different topology is attached.
EnumerationSwitchBinding	A binding that maps an EEnum value attribute of a System to a different topologies to be attached to a specified GroupNode. Different topologies can be assigned to the different enumeration values.
CircularSectorFieldOfViewBinding	A binding that binds the attributes (angular span and distance range) of an CircularSectorFieldOfView attribute of a System to the ones of a specified CircularSectorFieldOfView node in a topology.
ConicalFieldOfViewBinding	A binding that binds the attributes (field of view angle and distance range) of an ConicalFieldOfViewattribute of a System to the ones of a specified ConicalFieldOfView node in a topology.
RectangularFrustumieldOfViewBinding	A binding that binds the attributes (horizontal and vertical field of view angle and distance range) of an RectangularFrustumieldOfView of a System to the ones of a specified RectangularFrustumieldOfView node in a topology.
LightEnablementBinding	A binding that maps a boolean value a System to the enable state of a Light (ex: AmbientLight, DirectionalLight, PointLight, SpotLight).
PointLightBinding	A binding that binds the attributes (radius) of an PointLight of a System to the ones of a specified PointLight node in a topology.
SpotLightBinding	A binding that binds the attributes (range and spread angle) of an SpotLight of a System to the ones of a specified SpotLight node in a topology.