Difference between revisions of "Apogy/UserGuide"
|Line 123:||Line 123:|
=== Time Source ===
=== Time Source ===
=== Environment ===
=== Environment ===
Revision as of 10:51, 28 August 2018
Apogy User's Guide
Table Of Contents
- 1 Apogy User's Guide
- 1.1 Table Of Contents
- 1.2 Introduction
- 1.3 Concepts
- 1.3.1 Systems
- 1.3.2 Variables
- 1.3.3 Contexts
- 1.3.4 Time Source
- 1.3.5 Environment
- 1.3.6 Session
- 1.3.7 Time Sources
- 1.3.8 Types, Variables & Contexts
- 188.8.131.52 Types
- 184.108.40.206 Apogy System
- 220.127.116.11 Variables & API Adapters
- 18.104.22.168 Pose Corrector
- 22.214.171.124 Context
- 1.3.9 Data Products
- 1.3.10 Operation Calls & Programs
- 1.3.11 Controller Bindings & Configurations
- 1.3.12 Tools
- 1.3.13 Topology
- 1.4 Apogy UI
- 1.4.1 Preferences
- 1.4.2 Session Editor
- 1.4.3 Controllers View
- 1.4.4 Nodes Distance View
- 1.4.5 3D Viewer
- 1.4.6 Camera View
Apogy was originally developed at the Canadian Space Agency to control space exploration rovers and their associated sensors. Integrating all these system developed by many different contractors and allowing them to be controlled as an integrated entity represented a challenge. In order works, a tool to plan, validate, execute and monitor integrated operations to support multiple missions was required. The technical team soon realized that a reusable framework could save a lot of work and allow for future growth. Apogy is the result of this thinking.
Apogy was built to:
- Be an organizationally neutral core framework (we did not want to be locked in with any particular contractor proprietary tool);
- Maximizes reuse between missions (keep the work to the specifics of each mission);
In order to so, Apogy :
- Is a component-based architecture that allows systems (ex: instruments, rovers, satellites) to “plug-in” and allow the system developer to concentrate on their system specific needs and the tooling to use them.
- Makes use of Open Source librairies that are Eclipse Public License compatible;
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:
- The System Interface Class defining the commands and attributes it supports;
- A list of Connection Points where other sub-system can be attached;
- A list of Assembly Links that are used to assemble a System's sub-System (in composite Systems);
- A topology of nodes that are used to defined the system representation in 3D;
- 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 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 describe how systems are attached to each other in composite Systems.
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.
A use 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 are 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.
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 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, 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:
- myRover : Refers to a System which Interface Class is Rover, which has 2 sub-classes:
- RoverSimulated : A simulated implementation of the Rover;
- RoverReal : An implementation that connects to the actual hardware rover.
- myArm : Refers to a System which Interface Class is Arm, which has 2 sub-classes:
- ArmSimulated : A simulated implementation of the Arm;
- ArmReal : An implementation that connects to the actual hardware robot.
- 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:
- 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:
- A name (should be unique);
- 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).
Time Sources are used to feed the time to the Session. This in turns updates the position of the sky elements (Sun, Moon, Stars).
The Time Sources element contains the available Time Source, only one is set as the Session Active Time Source.
|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.|
The Environment contains the following:
- the Variables in use
- the list of available Contexts and the one currently active;
- the list of available Worksite and the one currently active;
- the list of available Time Source and the one currently active;
Contains the definitions of worksite, time sources and Systems;
Defines what the user has to work with in a specific mission such as the System instances.
- Contains the definitions of the Worksite, Time Sources and the registered Apogy Systems;
- Defines what you have to work with in a specific deployment;
- Defines the area that the System are operating in for the particular mission;
- Include a priori information about the area (e.g. Digital Elevation Maps (DEMs), orbital imagery, etc.);
Inherently generic concept that could be specialized as required (e.g. Earth surface);
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 a 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 referecens 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:
- the Environment being used;
- the list of available InitialConditions;
- Defines a Worksite that resides on the surface of a Celestial body (e.g. Earth)
- A component of a Worksite that contains Map Layers sharing a common pose relative to the Worksite origin;
- A Map Layer contains the actual data about the Worksite (e.g. DEM, Orbital Imagery, Slope, etc.);
- Currently support MapLayers:
- Triangular Mesh Map Layer (a meshed DEM);
- Features Of Interest Map Layer (specific locations in the Worksite);
- Image Map Layer (Image and its physical size on the Worksite);
- Contains the Celestial bodies of interest (Sun, Moon, Stars);
- Ephemerides updates based on time and the Worksite location;
- Represented in the Topology
- Time Sources are used to feed the time to the Session.
- This, in turn, updates the position of the sky elements (Sun, Moon, Stars);
- The Time Sources element contains the available Time Sources, only one of which is set as the Session Active Time Source;
- The Time Sources View can be used to access the various time source parameters.
Available Time Sources
|Fixed Time Source||A Time Source representing a fixed date and time.|
|Current Time Source||A Time Source that represents the current time, updated at a regular interval.|
|Selection-based Time Source||A Time Source that updates its time upon the selection of any Timed element in the UI.|
|Browseable Time Source||A Time Source that can be browsed, reset, played forward or reset, and accelerated.|
|Operation Calls Result List Time Source||A specialized Browseable Time Source that allows browsing a list of Operation Calls.|
Types, Variables & Contexts
- A Type defines an entity that can execute commands and provides telemetry:
- Similar to an Interface Control Document (ICD);
- Used to specify what a Variable represents;
- Type can include Type Members in their definitions;
- Types include an API Adapter that acts as a bridge between Apogy and the Interface Class;
- An Interface Class is the specific (i.e. real-world) Java type of the Apogy Type
- Is the "LEGO block" of Apogy;
- A System is a specialization of Type;
- Adds functions to assemble systems together through Connection Points and Assembly Links;
- Provide 3D representation of the System;
- A given System may have multiple implementations (e.g. Stub, Simulated, etc.);
- Implementation specific details transparent to Apogy: what matters is the interface.
Connection Points & Assembly Links
- A Connection Point represents a location in the System (as represented by a topology node) where another Type could connect to this System.
- An Assembly Link actually provides the link between a Connection Point and another Type.
- In the diagram below, one could say that the Connection Points act like hooks while the Assembly Links act like strings.
- It has no Type Member (i.e. it has no sub-systems);
- It typically represents a "building block" (sub-system) that can be used in the assembly of more complex Systems;
- Has one or more Type Members;
- Represents an assembly of sub-systems into an integrated System;
- Complex Systems can also be nested;
Variables & API Adapters
- A Variable is a reference to a Type (System) instance;
- A Variable name should be unique;
- Multiple Variables of the same Type can be defined;
- An API Adapter is the object that acts as a bridge between the System (i.e. the Interface Class) and Apogy;
- Automatically managed by Apogy;
- It provides:
- System to Apogy pose transformation and update functions;
- A Pose Corrector;
- A reference to the Variable / Type Member instance;
- A reference to the Apogy Environment;
- A Pose Corrector is used by the API Adapter to modify the System-derived pose before updating;
- Can be used to keep a vehicle on the ground;
- Can be enabled / disabled on the fly;
- A Context map Variables to an actual implementation through the Active Context;
- Used by Apogy to dispatch commands to System instances;
- A name (which should be unique)
- Where the results from operation invocations will be stored (i.e. Data Product Set);
- A hierarchy of Variable Implementation;
- A Variable Implementation is used to specify the particular implementation (i.e. an Interface Class subclass) that a Variable should be using.
- Typically used in Contexts
- A Data Product represents the result of an Operation Call;
- Conserves the operational context in which Operation was called;
- May have one or more 3D representations;
Data Products Set
- A Data Products Set contains all of the Data Products created with one or more Contexts:
- Allows data generated using different Contexts to be stored separately (for example, separating simulated and real data.)
- Each Context refers to a Data Products Set
Operation Calls & Programs
- A Program is an entity that invokes Operation Calls on Variables;
- A Program includes:
- A name;
- A description; and
- A list of Operation Calls
- An Operation Call is a specific invocation of an Operation on a Variable using a set of Parameters
- It contains:
- A reference to the Variable;
- References to a Variable type member and/or feature onto which to call the Operation (if applicable);
- An Operation to be called;
- A List of Parameters to use when calling the Operation;
- A Program in the form of a flat list of Operation Calls;
- Does not include execution flow control;
- Each Operation Call can be invoked individually, or
- It can be executed as a whole;
- A name;
- A description; and
- A script path relative to the workspace.
- It can be executed as a whole or
- It can be executed in debug mode and benefits from all the features of the JSDT framework (breakpoints, step by step...)
Controller Bindings & Configurations
- A Controller Configuration is a set of Operation Call Controller Bindings;
- Used to map one or more joystick(s) / controller(s) to one or more Operation Calls;
- No more than ONE Controller Configuration is active at any given time in a given Apogy Session;
Operation Call Controller Binding
- A Operation Call Controller Binding is a specialization of Operation Call;
- Allows the Operation Call's Parameter to be mapped to joystick inputs;
- It includes:
- A name;
- A Trigger that defines when to call this Operation Call:
- Can be time-based or joystick state-/event-based;
- An Input Value for each of the Parameters defined in this Operation Call.
- A boolean indicating whether or not to create a Data Product' when the Operation is called (false by default.)
|Time Trigger||[[File:../resources/user/trigger_time.gif]]||Triggers at a fixed time interval (or only once if time <= 0).|
|Controller Edge Trigger||[[File:../resources/user/trigger_controller_edge_rising.gif]]||Triggers when a rising edge is detected on the specified controller button state.|
|[[File:../resources/user/trigger_controller_edge_falling.gif]]||Triggers when a falling edge is detected on the specified controller button state.|
|[[File:../resources/user/trigger_controller_edge_both.gif]]||Triggers when either a rising or falling edge is detected on the specified button state.|
|Controller State Trigger||[[File:../resources/user/trigger_controller_state.gif]]||Triggers at a fixed time interval (or only once if time <= 0) if the specified controller button state (boolean) matches the target.|
- An Input Value defines how to obtain the value of its associated Parameter in an Operation Call Controller Binding.
- Three types of Input Value are defined:
- Fixed Value: A fixed value for the Parameter;
- Toggle Value: A boolean value that toggles each time the Operation is called;
- Controller Value: A value coming from a joystick input.
- A Controller Value includes:
- the joystick / controller;
- the specific input of the controller;
- an Input Conditioning used to transform the raw joystick value into a value suittable for the Parameter being mapped:
- This can include input scalling, input offsetting, saturation, dead-band,etc;
- Various specializations of Input Conditioning are available to accommodate these needs.
Input Conditioning Types
|Name||Icon||Description||Scaling Supported||Offset Supported||Dead Band Supported|
|Linear||[[File:../resources/user/input_conditioning_linear.gif]]||Linear transfer function with end points specified.||Yes||Yes||No|
|Centered Linear||[[File:../resources/user/input_conditioning_centered_linear.gif]]|| Linear transfer function with constraints that output is zero (0) for input falling within dead band.
Output linearly falls to zero at dead band limits.
|Parabolic||[[File:../resources/user/input_conditioning_parabolic.gif]]||Second-order transfer function with end points specified.||Yes||Yes||No|
|Centered Parabolic||[[File:../resources/user/input_conditioning_centered_parabolic.gif]]|| Parabolic output with constraint that output is zero (0) for input falling within dead band.
Slope is made continuous at dead band limits.
|User Defined||[[File:../resources/user/input_conditioning_user_defined.gif]]||Piecewise linear interpolation based on user-provided list of points.||No||No||No|
- The Tools element of the Session contains the tools defined by the user;
- Map View Configuration List
- Camera View Configuration List
- Recording Tools Container
- Simple Tool List
Map View Configurations
- A Map View Configuration List:
- contains Map View Configurations;
- A Map View Configuration object:
- defines what the Apogy Map View will display;
- defines the Map Layers to display;
- defines annotation to show vehicle position, FOV, etc.;
- defines map tools (e.g. Trajectory Picking Tool);
Camera View Configuration
- A Camera View Configuration List:
- contains Camera View Configurations;
- A Camera View Configuration object:
- defines what the Apogy Camera View will display;
- defines the Overlays to display;
- specifies image processing steps;
- defines image tools (e.g. Pointer Camera Tool);
- An Overlay represents graphics overlaid on top of the camera image.
- Apogy provides a list of basic, built-in Overlays;
- System-specific overlay can be contributed for a rover/instrument
|EMF Feature Overlay||[[File:../resources/user/overlay_emf_feature.gif]]||Displays any numerical or string value of a selected Feature on screen. The display includes the name of the Feature, its units, and the value.|
|Camera Name Overlay||[[File:../resources/user/overlay_camera_name.gif]]||Displays the name of the camera, if applicable.|
|Apogy Logo Overlay||[[File:../resources/user/overlay_apogy_logo.gif]]||Displays the Apogy Logo.|
|FOV Overlay||[[File:../resources/user/overlay_fov.gif]]||Displays a cross hair with marks indicating degrees along the vertical and horizontal axes, centered on the FOV origin. The values are binded to the current camera FOV.|
|EMF Feature Azimuth Elevation Overlay||[[File:../resources/user/overlay_emf_feature_azimuth_elevation.gif]]||Displays a cross hair with marks indicating degrees along the vertical and horizontal axes. The ABSOLUTE orientation is displayed. The values are bound to the current camera's Field of View (FOV) and the Azimuth and Elevation features selected.|
Built-in Image Filters
|Edge Filter||[[File:../resources/user/filter_edge.gif]]||Detects edges by looking at the gradient of each channel ands replaces the channel by a value determined by the gradient.|
|Gain Filter||[[File:../resources/user/filter_gain.gif]]||Changes the contrast of the image by allowing the user to specify the gain and bias of the colors in the image.|
|Gray Scale Filter||[[File:../resources/user/filter_gray_scale.gif]]|| Converts image to gray-scaled image. The formula used is:
luma = 77 R + 151 G + 28 B
|Invert Filter||[[File:../resources/user/filter_invert.gif]]||Inverts all of the pixels in an image. This is done by subtracting each colour component from 255.|
|Rescale Filter||[[File:../resources/user/filter_rescale.gif]]||Multiplies the input image by a scale factor.|
Built-in Camera Tools
|Pointer Camera Tool||[[File:../resources/user/camera_tool_pointer.gif]]||Allow the user to point in the camera image and then draws in the 3D environment, a ray showing where the selected position point projects into the 3D environment.|
- Apogy provides a few Simple Tools that are used with the Apogy 3D Viewer and other views;
- These tools act as a Selection Listener to the above views.
- Tool responds only if active;
- More than one tool can be active at the same time!
Built-in Simple Tools
|Ruler 3D Tool||[[File:../resources/user/simple_tool_ruler_3d.gif]]||Shows a ruler between two points.|
|Sun Vector 3D Tool||[[File:../resources/user/simple_tool_sun_vector_3d.gif]]||Shows the vector connecting the selected point to the current position of the Sun.|
|Feature Of Interest Picking Tool||[[File:../resources/user/simple_tool_feature_of_interest_picking.gif]]|| Allows the user to point and click to create a new Feature Of Interest.
Note that the Feature Of Interest List, where the Feature Of Interests are created, must be set for this tool to work.
|Trajectory 3D Tool||TODO!|
|Path Planner Tool||TODO!|
|Vehicle Path Planner Tool||TODO!|
|Telecom Status Monitor Tool||TODO!|
- The complete topology, including all that is present in the Apogy Environment:
- Variable instances;
- Data Products; and
- Types support definition of ranges for attributes and Operation Call Parameters;
- Colour used to highlight value ranges.
- Currently, Apogy does not provide colouring to the Properties Page cells;
- Types supports definitions of units for attributes and Operation Call Parameters;
- Allows conversion between Native Units (units used by the System) to Display Units (what you see);
- Applies to:
- values displayed in the Properties View;
- values entered in Operation Call Parameters;
- It is an Editor
- Is used to explore and edit Apogy elements;
- Presents the Apogy Session as an hierarchical tree of containment;
- Opens .sym files;
- Supports Undo/Redo
- Is a Selection Provider
- View is a singleton;
- Used to monitor all Controllers (joysticks) connected to the host;
- Shows all Controllers components including names, types and current values;
- Controllers conntected after Apogy has started will not be recognized!
Nodes Distance View
- Selection based (topology Node);
- Allows the selection of any two (2) nodes;
- Relative Euclidean distance;
- Relative geodesic distance;
- Relative position (x,y,z), given in metres;
- Relative orientation (rx, ry, rz), given in degrees;
- Supports real-time update.
- Selection based (Apogy Environment);
- Displays in 3D, the following elements:
- Variable instance
- Field Of Views
- Reference frames;
- The Earth Sky (Sun, Moon, Stars, grid)
- Map Layers that can be rendered in 3D
- Data Product marker for all products;
- Data Product 3D representations (when applicable);
- Tools 3D representations (when applicable).
- Displaying Data Products:
- All Data Products (marker + 3D representation) are visible by default;
- Is Selection Listener for Data Products
- Configuring 3D representations of topology Nodes:
- Each Node in the topology is assigned a Presentation that contains its 3D representation attributes.
- Presentation attributes are accessible using the Properties View, under the Presentation tab.
- Node visibility can be toggled by right-clicking on the Node and selecting "Apogy > Toggle Node Visibility."
- URL Nodes (Nodes associated with a CAD model) have an additional Presentation Mode attribute, which can be one of three values:
- SURFACE: The CAD will be rendered as a surface (if possible)
- WIREFRAME: Only the wireframe outline of the CAD surface will be rendered (if possible)
- POINTS: Only the point cloud specified in the CAD will be rendered (if possible)
- The visibility, Presentation Mode and colour can be set for all FOV of a given type through the Preferences;
- The visibility, and axis length can be set for all Node of a given basic type (Position, Rotation, Transform, URL) through the Preferences;
- The maximum frame rate (in Hz) can be lowered (default is 15 Hz);
- Under Field Of View and Image Snapshot preferences:
- Disabiling Show Project;
- Under Earth Sky preferences:
- Disabling Sun And Moon Blooming;
- Disabling Shadows;
- Reducing the Shadow Map Size;
Moving Using The Mouse
|Left||Rotate to the left|
|Right||Rotate to the right|
|Left||Translate to the right|
|Right||Translate to the left|
|Q||Quick: Accelerate translation|
|L||Level: Set view point orientation so that the user line of sight is level (perpendicular to the Z axis.)|
|P||Picking: Enables the picking mode(used by some 3D tools.) Picking Enabled shows up on the left hand side of the viewer when activated.|
- Selection-based (Camera View Configuration);
- Display latest image return by specified Camera;
- Display the Overlays;
- Applies the Image Filters before displaying the image
- Supports interaction with Camera Tools
- Selection-based (Map View Configuration);
- Selected Image Map Layers;
- Selected Feature Of Interest Map Layers;
- Various map annotations such as:
- Vehicle position and orientation;
Earth Sky View
- Selection-based (Earth Sky);
- Sun and Moon ephemerides as well as Sun intensity;
- The time at the Worksite:
- Local time;
- Julian day;
- Sideral time;
- The location of the Worksite:
Time Source View
Virtual Reality Tools
Data Products View