|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:
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.
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.
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.
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.
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.
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.
Graphics Overlay displaying a "Points" Shape
The NumberOfShapes property can be used to determine the number of shapes contained in a GraphicsOverlay.
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.
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:
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.
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.
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
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.
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:
Two-tone green triangle strip surrounding a Spacecraft
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:
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.
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.
•GraphicsOverlay Properties and Methods
•GraphicsOverlayShape Properties and Methods