Draw geo shapes
Publish points, lines, polygons, and ellipses as geo-entities on the map
A geo-entity is a shape, region, or point of interest drawn on the map, which may not physically exist. Use geo-entities to represent geographical areas of interest, such as an airfield, or a control zone for autonomous vehicles to operate in.
This page shows how to publish a polygon that defines a control area, and how to model the other shapes that Lattice supports: points, lines, and ellipses.
Before you begin
- To publish geo-entities, set up the Lattice SDK and set up a Lattice environment.
- Learn about the required components and entity templates in Lattice.
These gRPC examples authenticate with a static environment token attached as request metadata. If you are using OAuth 2.0 client credentials instead, set up the token refresh module before running the examples on this page.
Geo-entity components
In addition to the required components, a geo-entity uses the following components:
Set template
to TEMPLATE_GEO to render the entity as a shape on the map.
Set the geo_details type, such as
GEO_TYPE_GENERAL for a general shape or GEO_TYPE_CONTROL_AREA for a zone that
constrains autonomous vehicles.
Define the shape itself in geo_shape:
a point, line, polygon, or ellipse.
Publish a polygon
A polygon is the most common geo shape. It outlines an area, such as an airfield or a zone that autonomous vehicles must stay in or avoid. To publish a polygon that defines a loiter zone, do the following:
Define the entity
Define the entity model’s required components. Together with the geo-entity-specific components, you get the following entity object:
Define the shape
Take a closer look at the following components in entity_model.json. You define rings to
create the polygon. Each ring must have at least four points, each represented by a
position component.
The last point of a ring must be the same as its first point, which closes the shape.
Each point in the polygon has a minimum altitude defined as altitudeAglMeters.
The heightM component sets the additional height, in meters, above altitudeAglMeters.
This example defines a three-sided polygon that represents a loiter zone. Other control area
types include CONTROL_AREA_TYPE_KEEP_IN_ZONE and CONTROL_AREA_TYPE_KEEP_OUT_ZONE.
Publish the entity
Use the PublishEntity API method to publish the entity:
The example sets noExpiry instead
of expiryTime, so the polygon persists until you delete it. For more information, see
Keep shapes on the map.
Model other shapes
The other shapes use the same components as a polygon, with a different geo_shape:
Point
A point marks a single position, such as a rally point or a landing site. Set its position
in geoShape.point.position:
Line
A line connects two or more positions, such as a route or a boundary. List the positions in
order in geoShape.line.positions:
Ellipse
An ellipse describes a circular or oval area around a center point, such as a keep-out
radius. Set the center in location, and set the axes in meters and the orientation in degrees
in geoShape.ellipse. Equal axes produce a circle:
Keep shapes on the map
Most geo-entities describe areas that stay relevant across many operations, such as airfields and
control areas. For these shapes, set noExpiry to true instead of setting an expiryTime. Use
noExpiry only when the entity contains information that other tasks or integrations need beyond
its immediate operational context. Don’t set both noExpiry and expiryTime. Lattice rejects an
entity that sets both.
Even with noExpiry set to true, republish the entity at least every 5 minutes. If Lattice
restarts and an entity hasn’t been republished within the previous 5 minutes, Lattice doesn’t
restore it. The example code republishes the polygon in an indefinite loop.
To remove a shape, publish it again with isLive set to false.
What’s next?
- Use geo-entities as control areas when you task an asset.
- Follow shapes and tracks as they change with Cue and monitor.
- Explore every geo-entity field in the
PublishEntityAPI reference.