Path Primitive

The following example shows how to create a PathPrimitive, add/remove individual points, and add it to the scene:

PathPrimitive path = new PathPrimitive();

// add points to the back of the path
path.addBack(new PathPoint(new Cartesian(10000000.0, 10000000.0, 0.0), SceneManager.getTime(), Color.RED));
path.addBack(new PathPoint(new Cartesian(10000000.0, 11000000.0, 0.0), SceneManager.getTime(), Color.BLUE));

Color green = new Color(0x008000);
path.addBack(new PathPoint(new Cartesian(10000000.0, 12000000.0, 0.0), SceneManager.getTime(), green));

// render path with three points
SceneManager.getPrimitives().add(path);
getScene().render();

// remove point from the front of the path
path.removeFront();

// render path with remaining two points
getScene().render();

PathPoints can be added to either end of the path. Each PathPoint can have a different Color (get), Translucency (get), OutlineColor (get), and OutlineTranslucency (get). When a PathPoint is added to the PathPrimitive, the primitive does not sort the points by any of the properties mentioned above. The order the points were added to the path is the order they are on the line.

Notice that a PathPoint is an immutable object. The properties can only be set at construction time. Another way to create PathPoints is by using a PathPointBuilder, which has all of the same properties as a PathPoint, but they are mutable. It also contains convenience methods for using Cartographic positions. When finished building, a PathPoint can be created using the toPathPoint method.

PathPrimitive can add a range of PathPoints to the line as well. The following examples show use of PathPointBuilder and adding a range of points.

PathPointBuilder builder = new PathPointBuilder();
builder.setPosition(new Cartesian(10000000.0, 0.0, 0.0));
builder.setDate(SceneManager.getTime());
builder.setColor(Color.BLUE);

ArrayList<PathPoint> points = new ArrayList<PathPoint>();
for (int i = 0; i < 20; i++) {
    builder.setPosition(builder.getPosition().add(new Cartesian(100000.0, 0.0, 0.0)));
    points.add(builder.toPathPoint());
}

PathPrimitive path = new PathPrimitive();
path.addRangeToBack(points);

SceneManager.getPrimitives().add(path);
getScene().render();

PathPrimitive has other appearance properties that are used in the same way as PolylinePrimitive: PolylineType (get / set), Width (get / set), DisplayOutline (get / set), and OutlineWidth (get / set).

In addition, the UpdatePolicy (get / set) property also allows more direct control over updates. Any class that derives from PathPrimitiveUpdatePolicy can dynamically update the primitive when assigned to the UpdatePolicy (get / set) property. Several commonly used policies are provided. MaximumCountPathPrimitiveUpdatePolicy, will remove a point from the RemoveLocation (get / set) of the path when the number of points exceeds the MaximumCount (get / set). DurationPathPrimitiveUpdatePolicy will remove a point from the RemoveLocation (get / set) of the path when the time span between the point's Date (get) and the current Time (get / set) exceeds the Duration (get / set). The following code sample shows how to create your own update policy:

public static class DistancePathPrimitiveUpdatePolicy extends PathPrimitiveUpdatePolicy {
    public DistancePathPrimitiveUpdatePolicy(int distance, PathPrimitiveRemoveLocation removeLocation) {
        setDistance(distance);
        setRemoveLocation(removeLocation);
    }

    public final int getDistance() {
        return m_distance;
    }

    public final void setDistance(int value) {
        m_distance = value;
    }

    public final PathPrimitiveRemoveLocation getRemoveLocation() {
        return m_removeLocation;
    }

    public final void setRemoveLocation(PathPrimitiveRemoveLocation value) {
        m_removeLocation = value;
    }

    // remove points from the front/back of the line if the computed
    // distance is greater than the given distance.
    @Override
    public void update(PathPrimitive pathPrimitive, JulianDate date) {
        if (getRemoveLocation() == PathPrimitiveRemoveLocation.REMOVE_LOCATION_BACK) {
            while ((Cartesian.subtract(pathPrimitive.front().getPosition(), pathPrimitive.back().getPosition())).getLength() > getDistance()) {
                pathPrimitive.removeBack();
            }
        } else {
            while ((Cartesian.subtract(pathPrimitive.front().getPosition(), pathPrimitive.back().getPosition())).getLength() > getDistance()) {
                pathPrimitive.removeFront();
            }
        }
    }

    private int m_distance;
    private PathPrimitiveRemoveLocation m_removeLocation;
}

The following code assigns an update policy to a PathPrimitive:

PathPrimitive path = new PathPrimitive();
path.setUpdatePolicy(new DistancePathPrimitiveUpdatePolicy(6000000, PathPrimitiveRemoveLocation.REMOVE_LOCATION_BACK));

For an example that shows how to create a trail line for a satellite, see the HowTo, which includes an example showing how to add a handler to the SceneManager.TimeChanged (add / remove) that will add a new point to the back of the PathPrimitive at every animation update. It also uses a DurationPathPrimitiveUpdatePolicy to remove points from the front of the line. This technique is useful in real-time scenarios where new data is added to the line while older data is removed so as to not clutter the display with irrelevant data.