GEF/GEF4/Geometry

Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in the original wiki page.

Geometric Primitives

The API uses a small number of "primitives" which are globally used to build up, introspect and modify complex objects. These primitives are the Point, Angle and Dimension classes. Presumably, the most important class of the three is the Point class, because you will encounter it very often while working with the API. Point objects represent a point in two dimensional space.⁽¹⁾ From a list of Point objects, you can build up every planar geometry object.

Considering rotation and the angular relationship of two straight lines, Angle objects come into play. They abstract over two angle units: degrees and radians. The user has to specify the unit of the value an Angle object is constructed from. Moreover, the user can read the value of an Angle object in either degrees or radians. Therefore, the use of Angle objects assures that correct values are used in calculations. This indirection is done due to an inconsistency of several APIs, for example, org.eclipse.swt.graphics.Transform vs. org.eclipse.draw2d.geometry.Transform. Keep in mind that the GEF 4 Geometry API is not yet finished. Maybe, this indirection will be eliminated in a future version.

The Dimension class is the pendant of the draw2d.Dimension class.

(1) For the purpose of imagination, you can assume the coordinate system to be originated in the top left corner of your drawing area, expanding to the right and to the bottom.

Planar Geometry

This diagram depicts the interface hierarchy which underlies the individual geometry classes. It classifies the geometry classes mainly into either being ICurves or IShapes. An ICurve is a one dimensional geometry, i.e. the result that you get by drawing a continuous line with a pencil. It has a start and an end point, it is continuous and you can approximate it by a series of Bézier curves. On the other hand, an IShape is a two dimensional geometry, i.e. it continuously encloses a region on the drawing area, without holes. You can retrieve the outline of an IShape, which is an IPolyCurve, a special case of an ICurve. It defines a curve that is composed of multiple continuous ICurves and its purpose is to combine such a set of continuous curves to be able to operate on them as a whole.

Especially important for clipping, another class of planar geometries is introduced: the IPolyShape. Other than the relationship between ICurve and IPolyCurve, an IPolyShape is not an IShape. An IPolyShape is a (possibly) non-continuous set of IShapes. An example for an IPolyShape is a Region. A Region is the area that results from composing multiple Rectangles. It corresponds to the SWT Region.

An important part of a geometry API is the possibility to test the relationship of two geometry objects. The GEF 4 Geometry API provides four methods that perform relation tests. Universally usable is the touches() method for planar geometry objects. It tests if two objects have at least one point in common. Additionally, ICurves can be tested for intersections using the intersects() method and for an overlap using the overlaps() method, among each other. An IShape provides a contains() method to test if it fully contains a given planar geometry object. Moreover, the point test is available for arbitrary planar geometry objects. It tests if a given Point is incidental to the particular geometry object.

Supplementary to the intersects() test, a getIntersections() method is offered among ICurves. BézierCurves do also facilitate the extraction of overlapping segments via the getOverlap() method.

To achieve the full functionality of the API, you have to be aware of how the different planar geometry objects and their implemented interfaces are linked together. The fundamental ICurve is the BezierCurve, because every ICurve can be approximated by a set of continuous BezierCurves. This approximation can be received using the toBezier() method. The outline of an IShape always is an ICurve. You can retrieve it by using the getOutline() method on the particular shape. Furthermore, any planar geometry object can be transformed into a Path object by using its toPath() method.

The Path is special. It can hold any number of curves and shapes. But it does not implement the related interfaces. Therefore, you should only use the Path in situations where you really need it, because it does not provide such a rich interface as the other parts of the API.

So, let us consider a few examples.

1. Compute the points of intersection between a Line l1 and another Line l2:
   

   Point[] intersections = l1.getIntersections(l2);

2. Compute the points of intersection between a Line l and a Polygon p:
   

   Point[] intersections = l.getIntersections(p.getOutline());

3. Compute the points of intersection between a Polygon p1 and another Polygon p2:
   

   Point[] intersections = p1.getOutline().getIntersections(p2.getOutline());

This diagram depicts the inheritance hierarchy which underlies the individual geometry classes. It classifies the classes by their construction type, so that many operations are generalized in a few abstract classes. Additionally, the different planar geometry objects provide extra functionality, for example, computing the area of a Polygon, or unifying two Rectangles.

Line

• extends: BezierCurve
• implements: ICurve, ITranslatable, IScalable, IRotatable

Rectangle

• extends: AbstractRectangleBasedGeometry
• implements: IShape, ITranslatable, IScalable, IRotatable

Polyline

• extends: AbstractPointListBasedGeometry
• implements: IPolyCurve, ITranslatable, IScalable, IRotatable

Polygon

• extends: AbstractPointListBasedGeometry
• implements: IShape, ITranslatable, IScalable, IRotatable

Ellipse

• extends: AbstractRectangleBasedGeometry
• implements: IShape, ITranslatable, IScalable, IRotatable

Arc

• extends: AbstractArcBasedGeometry (which extends AbstractRectangleBasedGeometry)
• implements: ICurve, ITranslatable, IScalable, IRotatable

Pie

• extends: AbstractArcBasedGeometry (which extends AbstractRectangleBasedGeometry)
• implements: IShape, ITranslatable, IScalable, IRotatable

RoundedRectangle

• extends: AbstractRectangleBasedGeometry
• implements: IShape, ITranslatable, IScalable, IRotatable

QuadraticCurve

• extends: BezierCurve
• implements: ICurve, ITranslatable, IScalable, IRotatable

CubicCurve

• extends: BezierCurve
• implements: ICurve, ITranslatable, IScalable, IRotatable

BezierCurve

• extends: AbstractGeometry
• implements: ICurve, ITranslatable, IScalable, IRotatable

PolyBezier

• extends: AbstractGeometry
• implements: IPolyCurve, ITranslatable, IScalable, IRotatable

Region

• extends: AbstractPolyShape
• implements: IPolyShape, ITranslatable, IScalable, IRotatable

Ring

• extends: AbstractPolyShape
• implements: IPolyShape, ITranslatable, IScalable, IRotatable

Path

• extends: AbstractGeometry

Euclidean Geometry

Projective Geometry

Affine transformations

As you can see in the overview diagram, you can either transform your geometrical objects via instances of the AffineTransform class, or by using the short-cut methods provided by the ITranslatable, IScalable, IRotatable and IRotatableInPlace interfaces. Transformations can either be directly applied to an object, modifying the object in-place, or to a copy of the original object. This distinction is represented by the names of the short-cut methods. All names starting with 'get*' are applied to a copy of the original object. The other methods modify the object in-place.

Translation

Translating an object means moving the object. You can move an object in x- and y-direction. The associated distances can be passed to the translate(...)/getTranslated(...) methods either via two double precision floating point numbers, or via a Point object.

Scaling

Scaling an object means resizing the object. You can individually scale the object in x- and y-direction. Additionally, scaling requires a relative Point to scale away from. If you omit this Point, the scaling method will appropriately choose the relative Point. Normally, this will be the center Point of the geometric object that you want to scale.

Rotation

Rotation is special in that not all geometric objects can be rotated in-place. Rectangles, for example, are always parallel to the x- and y-axes. That's why a Rectangle does only provide the getRotated() short-cut methods for rotation. As with scaling, rotation is performed around a relative Point. If you omit this Point, the rotation method will appropriately choose it. Normally, this will be the center Point of the geometric object that you want to rotate.

Shearing

The short-cut methods for shearing are not yet implemented.

Conversions

From Geometry to SWT

via the toSWT...() methods

Tutorial

This is the documentation of the GEF4 Geometry API. You can find a small tutorial for the API here.