Package globus.glmap

Class GeometryBuilder

java.lang.Object
globus.glmap.GLNativeObject
globus.glmap.GeometryBuilder
All Implemented Interfaces:
AutoCloseable
public class GeometryBuilder extends GLNativeObject
A builder that constructs vector geometries (lines, polygons, multi‑lines, multi‑polygons) from a sequence of line strings and polygon rings.

Usage pattern:

  • Create an instance.
  • Optionally call beginPolygon() one or more times to define polygons.
  • Add lines via addLine(MapPoint[]) or addLineCb(int, GetPointBlock).
    • If a polygon is active (after beginPolygon()), each added line becomes a ring (first ring = outer boundary, subsequent rings = holes).
    • If no polygon is active, each added line becomes an independent line segment; multiple segments produce a multi‑line.
  • Call build() to obtain the final immutable geometry. The builder resets to its initial empty state afterwards.

Type inference:

  • If beginPolygon() was never called → a LineString (or MultiLineString if more than one line was added).
  • If beginPolygon() was called at least once → a Polygon (or MultiPolygon if beginPolygon() was called multiple times).

  • Constructor Details

    • GeometryBuilder

      public GeometryBuilder()
      Initializes an empty geometry builder. No geometry is present until lines are added.

  • Method Details

    • beginPolygon

      public void beginPolygon()
      Begins a new polygon definition.

      Must be called before adding rings for that polygon. After this call, all subsequent addLine(...) calls will be interpreted as linear rings belonging to the current polygon:

      • The first ring is the outer boundary.
      • All following rings are holes.

      To create a multi‑polygon, call beginPolygon() multiple times.

      See Also:

    • beginLine

      public void beginLine()
      Starts a new line string definition.

      After calling this method, subsequent calls to addPoint(MapPoint) or addPointLatLon(double, double) will append points to this line.

      See Also:

    • addLine

      public void addLine(@NonNull MapPoint[] points)
      Adds a line string to the current geometry.

      Behavior depends on the polygon context:

      • If a polygon is active (a previous call to beginPolygon() has been made and not yet built), the line becomes a ring of that polygon.
      • If no polygon is active, the line becomes an independent line segment. Multiple such calls will result in a multi‑line.
      Parameters:
      points - array of MapPoint defining the line.

    • addLineCb

      public void addLineCb(int count, @NonNull GeometryBuilder.GetPointBlock callback)
      Adds a line string using a callback function for point generation.

      Useful for computed geometries (circles, spirals, etc.). The behavior regarding polygon/line context is the same as addLine(MapPoint[]).

      Parameters:
      count - number of points to generate (must be ≥ 0).
      callback - a function that returns a MapPoint for each index from 0 to count‑1.

    • addPoint

      public void addPoint(@NonNull MapPoint point)
      Adds a point to the current geometry.
      Parameters:
      point - the point to add (must not be null)
      See Also:

    • addPointLatLon

      public void addPointLatLon(double lat, double lon)
      Adds a point specified by its latitude and longitude.

      This is a convenience method that accepts geographic coordinates in degrees. The coordinates are automatically projected to the internal coordinate system.

      Parameters:
      lat - latitude in degrees (range usually -90 … +90)
      lon - longitude in degrees (range usually -180 … +180)
      See Also:

    • build

      @Nullable public GLMapVectorObject build()
      Finalizes the building process and returns an immutable vector object containing all added geometries.

      The geometry type is inferred automatically:

      • If beginPolygon() was never called → a line string (or multi‑line if multiple lines were added).
      • If beginPolygon() was called at least once → a polygon (or multi‑polygon if called multiple times).

      After calling build(), the builder is reset to its initial empty state, ready to start a new geometry from scratch.

      Returns:
      a new GLMapVectorObject, or null if no geometry was added.

    • clear

      public void clear()
      Clears all added geometries and resets the builder to its initial empty state.

      Any ongoing polygon definition is discarded. After clear(), the builder behaves exactly as if it were newly created.