What is vector data?

Vector data consists of geometries such as lines, circles, or polygons, and is sometimes also referred to as features. Examples of vector data are buildings, roads, railways, stations, and so on.

To create a model containing vector data you can either use one of the model decoders provided for the format as listed in Supported data types, or create a model decoder as described in Supporting a custom vector format. When creating a model decoder for vector data yourself, or when modeling vector data without a model decoder, you can use a LuciadLightspeed shape to model (the geometrical part of) the domain objects.

When you are decoding a model, you must make sure that the coordinate reference system of the data is decoded too, as the model’s reference. For more information, see How to specify the georeference of your data.

LuciadLightspeed provides a number of shapes to model vector data. Depending on the geometry of the domain object, you can use a simple geometry such as a point, polyline, or bounding box to model the domain object. Or you can compose a more complex geometry using different simple geometries. It is also possible to model domain objects as a list of multiple (unconnected) shapes.

Each of the LuciadLightspeed shapes has a corresponding painter to render the shape in a 2D view as listed in LuciadLightspeed shape painters.

What is an ILcdShape?

A LuciadLightspeed shape (ILcdShape) is a geometrical object with a bounding box (ILcdBounds) and a focus (or center) point (ILcdPoint):

  • The bounding box is defined by a width, a height, and a depth, respectively the x, y, and z coordinates of the box. All shapes are essentially 3D. For 2D shapes, the z coordinate of ILcdBounds is either ignored or set to 0. To retrieve the bounds of a shape, use the getBounds method.

  • The focus point (or center point) of the shape is typically used as the handle or the labeling point of the shape in a GUI. You can retrieve the focus point using the getFocusPoint method.

Do not use ILcdBounds.getHeight instead of ILcdPoint.getZ to retrieve the height of a point. The height of the bounding box of a point is always 0 whereas the z coordinate of the point can have a value.

All LuciadLightspeed shapes implement ILcdShape and are available for both geodetic (LonLat) and Cartesian (XY) reference systems. For example, the implementation for 2D geodetic circles is TLcdLonLatCircle and the implementation for 2D Cartesian circles is TLcdXYCircle. Note that operations between shapes, such as containment tests, are only possible if the shapes are defined in the same reference system. An ILcdShape also has an editable variant, both for 2D and 3D shapes as described in Editable shapes.

Commonly used shapes briefly describes the main extensions of ILcdShape. Some of the extensions are described in more detail in a separate section. For a complete overview of all extensions and a more detailed description of all their properties and methods, see the API reference.

To find memory-saving implementations of LuciadLightspeed shapes in the API, search for classes that contain Float.

Editable shapes

An ILcd2DEditableShape is an extension of ILcdShape that allows users to edit the X/Y- or Lon/Lat-coordinates of a 2D shape using the following methods:

  • move2D: moves the shape to a given location. Usually, this method moves the focus point of the shape to the given location. But it is also possible to implement another move action.

  • translate2D: translates the shape over a given delta in both dimensions.

ILcd3DEditableShape is an extension of ILcd2DEditableShape and represents a shape that can be moved in three dimensions. The reason for providing separate 2D objects is because it saves memory. The implementing class of, for example a 2D point, only stores the first two coordinates in memory. For the third coordinate, it always returns 0.

Commonly used shapes

LuciadLightspeed provides the following commonly used shapes that all extend ILcdShape:

The interfaces ILcdComplexPolygon, ILcdPolygon, ILcdPolyline, and ILcdPolypoint are extensions of ILcdPointList. An ILcdPointList is an indexed list of ILcdPoint objects. Creating an ILcdPolyline or ILcdPolygon describes how to create an ILcdPolyline and ILcdPolygon.

What is an ILcdPoint?

An ILcdPoint is an ILcdShape representing a point in a 3D coordinate system. It is not possible to change an ILcdPoint, the interface only provides methods to retrieve properties. Its main methods are:

  • getX, getY, and getZ: to retrieve the first, second, and third coordinate of the point respectively.

  • getCosX, getCosY, getSinX, getSinY, getTanX, and getTanY: these methods are provided for efficiency reasons. Implementing classes can use these methods to retrieve and cache these values instead of recalculating them whenever they are needed.

  • cloneAs2DEditablePoint and cloneAs3DEditablePoint: to provide a copy that can be moved in two and three dimensions respectively.

Editable points

An ILcd2DEditablePoint is an ILcdPoint that you can move in two dimensions. It inherits the methods of the interfaces ILcdPoint and ILcd2DEditableShape. Similarly, an ILcd3DEditablePoint is an ILcdPoint that you can move in three dimensions. It inherits the methods of the interfaces ILcd2DEditablePoint and ILcd3DEditableShape.

ILcd2DEditablePoint and ILcd3DEditablePoint objects are often used as output arguments. These are arguments that are changed as a side effect of the method called. The use of output arguments avoids the creation of a new object for each call of the method. The name of a method or parameter with a side effect always ends in SFCT.

What is an ILcdBounds?

An ILcdBounds is a 3D box of which the sides are aligned with the coordinate axes of the associated coordinate system. It is specified by a location and a width, height, and depth that give the extents along the first, second, and third coordinate direction respectively. The location is specified by an ILcdPoint that represents the bottom left corner of the box. An ILcdBounds is typically used as bounding box for a more complex geometry. Because of its simple geometry, you can use it to speed up certain types of calculations. Its main methods are:

  • getLocation, getWidth, getHeight, and getDepth

  • interacts2D and interacts3D: to check if there is any kind of interaction, for example overlap or touching, with another ILcdBounds object.

  • contains2D and contains3D: to check if the ILcdBounds contains another ILcdBounds.

  • cloneAs2DEditableBounds and cloneAs3DEditableBounds: to provide a copy that can be moved in two and three dimensions respectively.

Editable bounding boxes

The interfaces ILcd2DEditableBounds and ILcd3DEditableBounds extend the interface ILcdBounds with methods to change the bounding box in two and three dimensions respectively.

To change an ILcd2DEditableBounds you can use one of the following methods:

  • move2D, translate2D, setWidth, and setHeight.

  • setToIncludePoint2D: to minimally extend the ILcd2DEditableBounds so that it includes a given ILcdPoint.

  • setTo2DIntersection: to calculate the intersection with a given ILcdBounds.

  • setTo2DUnion: to calculate the union with a given ILcdBounds. This method returns the smallest ILcdBounds that contains both ILcdBounds.

You can move an ILcd3DEditableBounds in three dimensions using methods that are equivalent to the methods provided by ILcd2DEditableBounds.

What is an ILcdShapeList?

An ILcdShapeList is an ILcdShape that is composed of multiple ILcdShape objects according to the Composite design pattern. The ILcdShape objects in an ILcdShapeList are ordered as shown in Figure 13, “An ILcdShapeList is a composite ILcdShape”. A shape list is useful for defining shapes that are topologically not connected. For example, countries with islands or with overseas areas. Its main methods are:

shapelist structure
Figure 13. An ILcdShapeList is a composite ILcdShape

What is an ILcdCurve?

An ILcdCurve is a continuous ILcdShape such as a line, an arc, or any connected combination of such shapes. The principal method of a curve is: void computePointSFCT(double aParam, ILcd3DEditablePoint aPointSFCT) whereby aParam can be between 0 and 1. Use this method to retrieve any point from the start point (aParam=0) until the end point (aParam=1) of the curve. You can also retrieve the start and end point of the curve using the getStartPoint and getEndPoint methods.

The following extensions are particularly noteworthy:

  • An ILcdCompositeCurve is composed of curves similarly as an ILcdShapeList is composed of shapes, but it is an ILcdCurve itself. Hence, all sub-curves are connected to each other. Together they form a new shape of which you can retrieve the points using a single parameter. The ILcdCompositeCurve starts at the start point of the first sub-curve and ends at the end point of the last sub-curve.

  • ILcdCircleBy3Points: a circle defined by a start control point, intermediate control point, and end control point.

  • The main sub-interfaces of ILcdCircularArc:

    • ILcdCircularArcByCenterPoint: an arc defined on a circle, using a center point, radius, start angle, and arc angle.

    • ILcdCircularArcByBulge: an arc defined on a circle, using the start point, end point, and the bulge factor. The bulge factor is the ratio between the distance from the center of the chord to the midpoint of the arc and the length of this chord.

    • ILcdCircularArcBy3Points: an arc defined on a circle, using the start point, end point, and a third point on the arc.

Creating an ILcdPolyline or ILcdPolygon

To create a TLcdLonLatPolyline or TLcdLonLatPolygon (and their Cartesian counterparts), you first need to create an ILcd2DEditablePointList as shown in Program: Creation of a TLcdLonLatPolygon object.

Program: Creation of a TLcdLonLatPolygon object (from samples/gxy/shapes/MainPanel)
private Object createLonLatPolygon(ILcdEllipsoid aEllipsoid) {
  ILcd2DEditablePoint[] points = {
      new TLcdLonLatPoint(3.4, 51.5),
      new TLcdLonLatPoint(4.3, 51.8),
      new TLcdLonLatPoint(5.2, 51.6),
      new TLcdLonLatPoint(5.2, 50.5),
      new TLcdLonLatPoint(3.7, 50.4),
  };
  ILcd2DEditablePointList pointList =
      new TLcd2DEditablePointList(points, false);
  return new TLcdLonLatPolygon(pointList, aEllipsoid);
}

Program: Creation of a TLcdLonLatPolygon object shows the steps involved with creating a TLcdLonLatPolygon:

  1. Create an array of ILcd2DEditablePoint objects (with instances of the class TLcdLonLatPoint).

  2. From this array create an ILcd2DEditablePointList (which is an instance of the class TLcd2DEditablePointList).

  3. From the ILcd2DEditablePointList create a TLcdLonLatPolygon.

These steps are similar for the creation of a TLcdXYPolygon, TLcdLonLatPolyline, and TLcdXYPolyline.

Notifying objects of changes to shapes

Whenever a shape changes, LuciadLightspeed automatically notifies registered objects of the change using the Listener pattern, as described in Listening to changes in the selection. The following specific cases, are an exception to this rule:

  • Changing the values of an object that is contained in another (composite) object. In this case, the action object needs to use the method ILcdInvalidateable.invalidateObject to notify the composite object of the change. The composite object can then for example recompute its cached values. An example of this case is an ILcdShapeList.

  • Editing a shape of ILcdEditableShapeList. In this case, the action object needs to use the method shapeChanged to notify the ILcdEditableShapeList of the change.

  • Changing the base shape of an ILcd2DEditableGeoBuffer. In this case, the action object needs to use the method invalidateShape to notify the ILcd2DEditableGeoBuffer of the change.