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 thegetBounds
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 |
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 |
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
:
-
ILcdArc
: an elliptical arc. All points of an arc are located on an ellipse. The arc starts at a start angle and extends over an arc angle. You can rotate its semi-major axis.Figure 1. AnILcdArc
-
ILcdArcBand
: a circular arc with a width. All of its points are located on the band with a minimum radius and a maximum radius from the focus point. The arc band starts at a start angle and extends over an arc angle.Figure 2. AnILcdArcBand
-
ILcdBounds
: a box with a location (ILcdPoint
), a width, a height, and a depth.ILcdBounds
is often used as a bounding box for more complex shapes. For more information, see What is an ILcdBounds?.Figure 3. AnILcdBounds
-
ILcdCircle
: a circle with a focus point (ILcdPoint
) and a radius.Figure 4. AnILcdCircle
-
ILcdCircularArc
: a circular arc. All of its points are located on a circle with a focus point (ILcdPoint
) and a radius. The arc starts at a start angle and extends over an arc angle. Refer to What is an ILcdCurve? for the main sub-interfaces ofILcdCircularArc
.Figure 5. AnILcdCircularArc
-
ILcdComplexPolygon
: a list ofILcdPolygon
objects that results in a polygon with one or more holes. Each hole is a polygon as shown in Figure 6, “AnILcdComplexPolygon
”.Figure 6. AnILcdComplexPolygon
-
ILcdEllipse
: an ellipse with a focus point (ILcdPoint
), a semi-major axis with a rotation angle, and a semi-minor axis.Figure 7. AnILcdEllipse
-
ILcdGeoBuffer
: a shape (ILcdShape
) with a surrounding buffer that is defined by a width.Figure 8. AnILcdGeoBuffer
-
ILcdPolygon
: a closed polyline defined by multiple points and an orientation.Figure 9. AnILcdPolygon
-
ILcdPolyline
: a line defined by multiple points.Figure 10. AnILcdPolyline
-
ILcdPolypoint
: a set of points.Figure 11. AnILcdPolypoint
-
ILcdPoint
: a single point. For more information, see What is an ILcdPoint?. -
ILcdCurve
: a continuousILcdShape
. For more information, see What is an ILcdCurve?. -
ILcdRing
: a closedILcdCurve
, which means that the start and end point of the ring are the same. Since rings can be filled, they form the basis for surfaces. -
ILcdShapeList
: a set ofILcdShape
objects. For more information, see What is an ILcdShapeList?. -
ILcdSurface
: a continuous 2D shape of which the exterior boundary is defined by a singleILcdRing
. A surface contains zero or more holes. Each hole is also defined by anILcdRing
. -
ILcdText
: a text string defined by a location (ILcdPoint
), a character width and a character height, a horizontal and a vertical alignment, and a rotation angle.Figure 12. AnILcdText
The interfaces |
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
, andgetZ
: to retrieve the first, second, and third coordinate of the point respectively. -
getCosX
,getCosY
,getSinX
,getSinY
,getTanX
, andgetTanY
: 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
andcloneAs3DEditablePoint
: 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
.
|
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
, andgetDepth
-
interacts2D
andinteracts3D
: to check if there is any kind of interaction, for example overlap or touching, with anotherILcdBounds
object. -
contains2D
andcontains3D
: to check if theILcdBounds
contains anotherILcdBounds
. -
cloneAs2DEditableBounds
andcloneAs3DEditableBounds
: 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
, andsetHeight
. -
setToIncludePoint2D
: to minimally extend theILcd2DEditableBounds
so that it includes a givenILcdPoint
. -
setTo2DIntersection
: to calculate the intersection with a givenILcdBounds
. -
setTo2DUnion
: to calculate the union with a givenILcdBounds
. This method returns the smallestILcdBounds
that contains bothILcdBounds
.
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:
-
getShape
: to retrieve theILcdShape
at a given index in theILcdShapeList
. -
getShapeCount
: to retrieve the number ofILcdShape
objects in theILcdShapeList
.
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 anILcdShapeList
is composed of shapes, but it is anILcdCurve
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. TheILcdCompositeCurve
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.
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
:
-
Create an array of
ILcd2DEditablePoint
objects (with instances of the classTLcdLonLatPoint
). -
From this array create an
ILcd2DEditablePointList
(which is an instance of the classTLcd2DEditablePointList
). -
From the
ILcd2DEditablePointList
create aTLcdLonLatPolygon
.
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 anILcdShapeList
. -
Editing a shape of ILcdEditableShapeList. In this case, the action object needs to use the method
shapeChanged
to notify theILcdEditableShapeList
of the change. -
Changing the base shape of an ILcd2DEditableGeoBuffer. In this case, the action object needs to use the method
invalidateShape
to notify theILcd2DEditableGeoBuffer
of the change.