Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Apogy/Concepts

< Apogy
Revision as of 11:13, 4 September 2018 by Pierre.allard.canada.ca (Talk | contribs) (Operation Call File:Apogy_OperationCall_icon.gif)

Table Of Contents

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.

The following tables presents a brief summary of the Concept defined in Apogy. Please refer to the sub-sections for more details.

Session Apogy Session icon.gif

In Apogy, the Session Apogy Session icon.gif 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 Apogy ApogySystem icon.gif

In Apogy, a System Apogy ApogySystem icon.gif 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 methods and attributes of the System. Only methods 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. For 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. connection points (yellow rectangles) and topology Nodes (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 Apogy Context icon.gif

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 Apogy Context icon.gif . 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 active. Real Context active.
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 Apogy TimeSourcesList icon.gif and the one currently active;

Time Source Apogy TimeSourcesList icon.gif

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.
Apogy CurrentTimeSource icon.gif 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.
Apogy BrowseableTimeSource icon.gif 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 Apogy Sun icon.gif and a StarField Apogy StarField icon.gif

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 Apogy Sun icon.gif

The Sun Apogy Sun icon.gif 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 Apogy Moon icon.gif

The Moon Apogy Moon icon.gif 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 Apogy StarField icon.gif

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

Each Star Apogy Star icon.gif includes:


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 left 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.

Earth Surface Worksite Apogy EarthSurfaceWorksite icon.gif

This specialization of # Surface Worksite for working on the surface of the Earth. The Earth Surface Worksite Apogy EarthSurfaceWorksite icon.gif includes the following:

  • The Geographical Coordinates Apogy GeographicCoordinates icon.gif (longitude, latitude and altitude) of its origin;
  • The angle (XAxisAzimuth) between is X axis and true North.
  • An Earth Sky which includes:

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 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;

Program

A Program is an entity that invokes Operation Calls on Variables .

Operation Call Apogy OperationCall icon.gif

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 Parameters to use when calling the Operation;

Initial Conditions Apogy InitialConditions icon.gif

Apogy defines Initial Conditions Apogy InitialConditions icon.gif 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.

Tool

Topology

TODO

Topology Bindings

TODO

Copyright © Eclipse Foundation, Inc. All Rights Reserved.