Polyline Primitive

The following code sample shows how to create a polyline with two points:

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
Cartographic philadelphia = new Cartographic(Trig.DegreesToRadians(-75.25), Trig.DegreesToRadians(39.88), 3000.0);
Cartographic washingtonDC = new Cartographic(Trig.DegreesToRadians(-77.04), Trig.DegreesToRadians(38.85), 3000.0);

List<Cartographic> positions = new List<Cartographic>
{
    philadelphia,
    washingtonDC
};

PolylinePrimitive line = new PolylinePrimitive();
line.SetCartographic(earth, positions);
SceneManager.Primitives.Add(line);

An equally useful use-case is rendering several line segments with one polyline primitive. Line segments can be connected, as they would be for a country border, or independent, as they would be for individual aircraft routes. The Set and SetCartographic methods can also be used to define a polyline with several line segments. They take a collection of positions that define the polyline.

The type of line can be specified when constructing a polyline. When PolylineType.LineStrip is used, the positions define a connected line strip. After the first position, each additional position connects to the previous. When PolylineType.Lines is used, every two positions define an individual line segment. The difference is shown in the images below:

Line Strip

Lines

The following example initializes a polyline with 3 line segments:

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(1.0), 0.0, 0.0),
    new Cartographic(Trig.DegreesToRadians(3.0), 0.0, 0.0),
    new Cartographic(0.0, Trig.DegreesToRadians(1.0), 0.0),
    new Cartographic(0.0, Trig.DegreesToRadians(3.0), 0.0),
    Cartographic.Zero,
    new Cartographic(Trig.DegreesToRadians(3.0), Trig.DegreesToRadians(3.0), 0.0)
};

PolylinePrimitive line = new PolylinePrimitive(PolylineType.Lines);
line.SetCartographic(earth, positions);

SceneManager.Primitives.Add(line);

Polylines support the standard color properties: Color and Translucency, which affect every line segment. Polylines can also be rendered with an outline by using DisplayOutline, OutlineColor, OutlineTranslucency, and OutlineWidth, as shown in the images below:

A polyline without outline

A polyline with a 2-pixel black outline

To define a polyline with per-line segment colors, use the Set or SetCartographic method, which takes a separate collections of colors, one color per position.

Each color in the collection corresponds to a position in the positions collection, so the number of colors must match the number of positions. Currently, flat shading is used; of the two positions that define a line segment, the color of the second one is used for the color of the line segment.

The following example uses a polyline to render 3 lines, each with a different color.

List<Cartesian> positions = new List<Cartesian>
{
    new Cartesian(1000000.0, 0.0, 0.0),
    new Cartesian(7000000.0, 0.0, 0.0),
    new Cartesian(0.0, 1000000.0, 0.0),
    new Cartesian(0.0, 7000000.0, 0.0),
    new Cartesian(0.0, 0.0, 1000000.0),
    new Cartesian(0.0, 0.0, 7000000.0)
};

List<Color> colors = new List<Color>
{
    Color.Blue,
    Color.Blue,
    Color.Orange,
    Color.Orange,
    Color.White,
    Color.White
};

PolylinePrimitive line = new PolylinePrimitive(PolylineType.Lines);
line.Set(positions, colors);
line.ReferenceFrame = CentralBodiesFacet.GetFromContext().Earth.InertialFrame;

SceneManager.Primitives.Add(line);

To facilitate dynamic updates, polylines provide SetPartial and SetPartialCartographic methods. See the Dynamic Updates Dynamic Updates topic for more information.

A theme throughout primitives is to decouple computation from rendering. For the polyline, this means that an interpolator can be provided as input along with positions to the polyline. The interpolator computes the actual positions rendered. When a polyline is dynamically changed, the interpolator is automatically called. This makes the polyline useful for rendering a wide range of line-based objects: lines, great arcs, rhumb lines, splines, etc.

Great arcs are paths on the surface that represent the shortest distance between positions. They are rendered by passing a great arc interpolator to a polyline as shown below.

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(61.22), Trig.DegreesToRadians(-149.85), 0.0),
    new Cartographic(Trig.DegreesToRadians(-22.54), Trig.DegreesToRadians(-43.14), 0.0)
};

PolylinePrimitive line = new PolylinePrimitive(new GreatArcInterpolator());
line.SetCartographic(earth, positions);

SceneManager.Primitives.Add(line);

The following image shows the result:

Rhumb lines are lines of constant bearing. They appear as straight lines on a Mercator 2D map projection and are well suited to navigation. Replace GreatArcInterpolator in the above code example with RhumbLineInterpolator to render a rhumb line. The result is shown below:

To maintain a constant bearing, the rhumb line appears to spiral, unlike the great arc which is the shortest distance between the points.

When a polyline is constructed with no interpolator, no interpolator is used. This is always faster than using an interpolator since no interpolated positions need to be computed and no extra memory will be allocated. It is common to not use an interpolator when the vertices are not on the surface or are already close enough together that the line doesn't appear to cut through the globe.

Both the great arc and rhumb line interpolators provide a Granularity property that is used to control the number of interpolated positions. The default is 1 degree. Decrease the granularity to add more positions or increase it to add fewer positions. However, note that making the granularity too high will result in lines cutting through the globe, as the following example demonstrates.

CentralBody earth = CentralBodiesFacet.GetFromContext().Earth;
List<Cartographic> positions = new List<Cartographic>
{
    new Cartographic(Trig.DegreesToRadians(61.22), Trig.DegreesToRadians(-149.85), 0.0),
    new Cartographic(Trig.DegreesToRadians(-22.54), Trig.DegreesToRadians(-43.14), 0.0)
};

PolylinePrimitive line = new PolylinePrimitive(new RhumbLineInterpolator(earth, Trig.DegreesToRadians(30.0)));
line.SetCartographic(earth, positions);

SceneManager.Primitives.Add(line);