GraphicsOverlays

Top  Previous  Next

The GraphicsOverlay object in FreeFlyer allows you to display custom graphics on 2D or 3D output views. A GraphicsOverlay consists of one or more shapes, and each shape may contain multiple overlay elements. The following shape types are available:

 

Lines

Annotations

Points

Triangles

Triangle Strips

Icons

 

A single GraphicsOverlay object may contain multiple shapes of different types. A GraphicsOverlay is referenced to an object that is displayed in a ViewWindow, such as a Spacecraft or the Earth. If desired, WindowOverlay objects allow you to display content referenced to the bounds of the ViewWindow itself.

 

There are a variety of Sample Mission Plans (included with your FreeFlyer installation) that demonstrate various applications of these topics. Continue to the Generating Output page to view descriptions and images of these examples or jump to one of the Mission Plans listed below.

 

 

 

Creating a GraphicsOverlay


The GraphicsOverlay object can be created in the Object Browser, but can only be edited in FreeFlyer script. By default, a GraphicsOverlay's reference object is set to the Earth. The reference object is the FreeFlyer object to which the overlay geometry is referenced. An example of changing the reference object is shown below.

 

// Create Graphics Overlay

GraphicsOverlay GraphicsOverlay1;

GraphicsOverlay1.SetReferenceObject(Spacecraft1.ObjectId);

 

The following properties control the location of the GraphicsOverlay as a whole. Note that specific locations for each element are referenced from the location given by these properties.

 

Position - The offset position of the GraphicsOverlay with respect to the body fixed coordinate system of the ReferenceObject

Orientation - The quaternion orientation of the GraphicsOverlay with respect to the body fixed coordinate system of the ReferenceObject

Scale - The x, y, and z scaling factors of the GraphicsOverlay

 

// Setting a custom offset for the location of the overlay

GraphicsOverlay1.Position = {1000, 0, 500};

GraphicsOverlay1.Orientation = {0, 0.1, 0, 0.2};

GraphicsOverlay1.Scale = {0, 10, 0};

 

Note: The order of transformations is scaling, then rotation, and finally translation.

 

 

Adding Elements to a Shape


When a GraphicsOverlay is created, a default "Lines" shape type is created as the first shape. To add data points to the Line, use the AddOverlayElement method as shown below.

 

// Define line width

GraphicsOverlay1.Shapes[0].SetLineWidth(0 /* Relative */, 1);

 

// Draw a line using two points

GraphicsOverlay1.AddOverlayElement(x1, y1, 0);

GraphicsOverlay1.AddOverlayElement(x2, y2, 0);

 

// Draw a line and specify a custom color

GraphicsOverlay1.AddOverlayElement(x3, y3, 0, RGB(0,1,0));

GraphicsOverlay1.AddOverlayElement(x4, y4, 0, RGB(0,1,1));

 

Graphics Overlay showing a line drawn in the Earth X-Y plane with fading colors

Graphics Overlay showing a line drawn in the Earth X-Y plane with fading colors

 

By default, the AddOverlayElement method expects you to specify data points as X, Y, Z values. However, you also have the option to input RA, Dec, Radius points. In this case you will add an additional "mode" argument to the beginning of the method call, as seen in the example below.

 

// Specify XYZ points

GraphicsOverlay1.AddOverlayElement("x-y-z", x1, y1, z1);

GraphicsOverlay1.AddOverlayElement("x-y-z", x2, y2, z2);

 

// Specify RA-Dec-Radius points

GraphicsOverlay1.AddOverlayElement("ra-dec-radius", RA1, Dec1, Rad1);

GraphicsOverlay1.AddOverlayElement("ra-dec-radius", RA2, Dec2, Rad2);

 

This AddOverlayElement method is used to add data points to any of the GraphicsOverlay shape types, as seen in the example throughout this page.

 

Note: Care should be taken populating a large GraphicsOverlay shape when batch updating a ViewWindow using the ViewWindow.BeginBatchUpdate() and ViewWindow.EndBatchUpdate() methods. In this situation it is recommended that the ViewWindow be updated using a single Update command rather than updating after each overlay element is added to the GraphicsOverlay shape.

 

 

Adding Shapes to an Overlay


You can add additional shapes to a GraphicsOverlay using the AddShape method. There is also a RemoveShape method available for deleting shapes from an overlay. Every newly added shape will be a "Lines" shape type, but you can override a shape's type by setting the ShapeType property. The example below shows how to add a new shape using the AddShape method, change its type to Points, and add data points to the new shape.

 

// Draw a set of three points by specifying the x, y, z locations

// Remember, these locations are referenced to the GraphicsOverlay's reference object.

GraphicsOverlay1.AddShape();

GraphicsOverlay1.ShapeType = "Points";

GraphicsOverlay1.AddOverlayElement(x1, y1, z1);

GraphicsOverlay1.AddOverlayElement(x2, y2, z2);

GraphicsOverlay1.AddOverlayElement(x3, y3, z3);

 

Graphics Overlay displaying a "Points" Shape

Graphics Overlay displaying a "Points" Shape

 

The NumberOfShapes property can be used to determine the number of shapes contained in a GraphicsOverlay.

 

Report GraphicsOverlay1.NumberOfShapes;

 

Note: If you specify an annotation when adding an overlay element (ie, GraphicsOverlay1.AddOverlayElement(x, y, z, "annotation");), this will cause the shape type for the current shape to be set to "Annotations". Changing the shape type for any shape causes any previous configuration for that shape to be cleared.

 

Setting the Active Shape

Note that the AddOverlayElement method adds the data points to the currently active shape (in the example above, this was a "Points" shape). To edit properties of a previous shape, you can set the CurrentShapeIndex property to allow you to specify which shape you would like to edit.

 

// Set the Current Shape Index in order to access a previous shape in the overlay

GraphicsOverlay1.CurrentShapeIndex = 0;

 

The CurrentShapeIndex determines which shape is edited when you use a variety of the properties and methods available for the GraphicsOverlay. The properties and methods whose behavior depends on the CurrentShapeIndex include:

 

Properties

oShapeType - The shape type of the active shape

oNumberOfVertices - The number of vertices in the currently active shape

oVertices - The locations of the overlay points in the currently active shape

oNumberOfAnnotations - The number of annotations in the currently active shape

oAnnotationColors, AnnotationFont, AnnotationLabels, AnnotationLocations - The annotation properties of the currently active shape

oShapeIconFileName - Specifies an image to draw at each vertex of the active shape

oShapeOpacity - The opacity of the active shape

oShapeOrientation - The quaternion orientation of the active shape

oShapePosition - The offset position of the active shape

oShapeScale - The x, y, and z scaling factors of the active shape

oShapeTickType - Specifies which tick mark type to draw at each vertex of the active shape. Tick marks will be drawn for 'Lines', 'Annotations', 'Points', and 'Icons' shape types only.

oShapeVisible - Determines whether the active shape is visible

oShowTextBackDrop - Determines whether a translucent black rectangles is drawn behind annotations in the 2d map mode of the Mission View for the active shape

Methods

oAddOverlayElement - Adds an element to the active shape of the GraphicsOverlay

oClearOverlayElements - Clears all elements associated with the active shape of the GraphicsObject overlay

 

Note: When working with the shape position, orientation, and scale properties, the order of shape transformations is scaling, then rotation, and finally translation.

 

 

Advanced Shape Types


While working with Lines, Points, and Annotations is fairly straightforward, allowing the user to simply specify the locations for each data point to be added, the options for some shapes are more complex.

 

Triangles

When working with the Triangles shape type, you have the ability to specify the vertices that define an unlimited number of triangles. Every group of three points that you add using the AddOverlayElement method will add a new triangle. The triangles will not be automatically connected in any way, unlike the Triangle Strip option discussed below.

 

This example shows how to create a Triangle shape in a GraphicsOverlay and add three triangles to the shape, each displayed in a different color as seen in the image below.

 

// Add a shape to the overlay which will contain a single blue triangle

GraphicsOverlay1.AddShape();

GraphicsOverlay1.ShapeType = "Triangles";

 

// Add Overlay elements to the currently active shape

 

// This will draw a blue triangle at the north pole

GraphicsOverlay1.AddOverlayElement(-1000,1000,Earth.Radius + 100);

GraphicsOverlay1.AddOverlayElement(1000,1000,Earth.Radius + 100);

GraphicsOverlay1.AddOverlayElement(0,-1000,Earth.Radius + 100,RGB(0,0,1));

 

 

// This will draw a cyan triangle on the equator

GraphicsOverlay1.AddOverlayElement(1000,-Earth.Radius - 100,-1000);

GraphicsOverlay1.AddOverlayElement(1000,-Earth.Radius - 100,1000);

GraphicsOverlay1.AddOverlayElement(-1000,-Earth.Radius - 100, 0,RGB(0,1,1));

 

 

// This will draw a magenta triangle on the equator

GraphicsOverlay1.AddOverlayElement(-Earth.Radius - 100,1000,-1000);

GraphicsOverlay1.AddOverlayElement(-Earth.Radius - 100,1000,1000);

GraphicsOverlay1.AddOverlayElement(-Earth.Radius - 100,-1000, 0,RGB(1,0,1));

 

 

Triangle Strips

When working with Triangle Strips, again you have the ability to define the vertices for an unlimited number of triangles. The first three points that you set using the AddOverlayElement method will form the first triangle. Then, each additional point you specify will be used to create a new triangle that is formed using the three most recent points.

 

The image below illustrates this concept. The first three points form the first triangle: 123. The fourth point is added to form a second triangle: 234. As more points are added, new triangles are formed: 345, 456, 567, and so on.

Image illustrating the concept of Triangle Strips

Image illustrating the concept of Triangle Strips

 

This functionality is very powerful and can be used to create many complex geometries. In the example below, we use basic trigonometric functions to create a triangle strip that forms a solid band, as shown in the image below.

 

// Create GraphicsOverlay referenced to a Spacecraft

GraphicsOverlay GraphicsOverlay1;

GraphicsOverlay1.SetReferenceObject(Spacecraft1.ObjectId);

 

// Set the shape type to Triangle Strip and make the strip green and slightly translucent

GraphicsOverlay1.ShapeType = "Triangle Strip";

GraphicsOverlay1.DefaultColor = RGB(0,1,0);

GraphicsOverlay1.ShapeOpacity = 0.8;

 

For i = 0 to 100;

 

     // Calculate 100 evenly-spaced angles spanning from 0 to 360 degrees

     angle = rad(360.0 * i/100.0);

 

     x = cos(angle);

     y = sin(angle);

 

     // Add overlay elements to the active shape

     // This will draw a ring around the spacecraft with a 1000 km radius

     // and a 200 km thickness

 

     // X-Y plane triangle strip

     GraphicsOverlay1.AddOverlayElement(1000*x,1000*y,-100);

     GraphicsOverlay1.AddOverlayElement(1000*x,1000*y,100);

 

End;

 

Green triangle strip surrounding a Spacecraft

Green triangle strip surrounding a Spacecraft

 

If we modify the script to use a different color for every second triangle, the output image will show more clearly how the ring is formed:

 

//...

     // X-Y plane triangle strip

     GraphicsOverlay1.AddOverlayElement(1000*x,1000*y,-100, RGB(0,1,0));

     GraphicsOverlay1.AddOverlayElement(1000*x,1000*y,100, RGB(.2,.8,.2));

//...

 

Two-tone green triangle strip surrounding a Spacecraft

Two-tone green triangle strip surrounding a Spacecraft

 

Icons

The Icons shape type allows you to specify an image file to draw at each vertex specified using the AddOverlayShape method. The icon image will be drawn in 2D map views only. Supported image formats include PNG, TIF, JPG, BMP, and GIF. When working with Icons, you have access to a few additional properties and methods that only apply for this shape type:

 

ShapeIconFileName - Specifies an image to draw at each vertex of the active shape

ShapeIconReferencePoint - Determines which point on the image will be located at the specified vertices. Valid values are:

oCenter

oUpper Left

oLower Left

oUpper Right

oLower Right

ShapeIconRotation - The clockwise rotation of the icon about the ShapeIconReferencePoint in degrees

ShapeIconScale - A scale, specified in kilometers, determining how large the icon will be drawn on the 2d map

oThe image will be drawn with a height proportional to the specified scale

oThe width will be automatically selected as to maintain the original aspect ratio of the image

oFor example, mapping a celestial object with a circumference of 2000 km and an icon scale of 500 km, the image will be drawn at half the height of the entire map when fully zoomed out

oThe default value is 1000

 

The example below illustrates how to add a new shape to a GraphicsOverlay, set its type to "Icons", configure the icon file name, and display the icon at three separate locations on the 2D Map.

 

// Add a shape to the overlay which will contain an image from an external file

GraphicsOverlay1.AddShape();

GraphicsOverlay1.ShapeType = "Icons";

 

// Set the file name and display options

GraphicsOverlay1.ShapeIconFileName = "..\_Support_Files\ailogo.png";

GraphicsOverlay1.ShapeOpacity = 0.8;

GraphicsOverlay1.ShapeIconScale = 2000;

 

// Add an Overlay element to the currently active shape

// This will draw the same image at three locations on the equator

GraphicsOverlay1.AddOverlayElement(Earth.Radius + 1000,0,0);

GraphicsOverlay1.AddOverlayElement(0,Earth.Radius + 1000,0);

GraphicsOverlay1.AddOverlayElement(0,-Earth.Radius - 1000,0);

 

Graphics Overlay displaying an image file at three locations on the equator

Graphics Overlay displaying an image file at three locations on the equator

 

Note: If you want to display images from multiple input files, you must create a new shape within the GraphicsOverlay for each file using the AddShape method.

 

 

See Also


GraphicsOverlay Properties and Methods

GraphicsOverlayShape Properties and Methods