Map Utilities API

Source: raptor/errors.hpp, raptor/query.hpp, raptor/render.hpp, raptor/analyze.hpp

Types

Name	Description
MapQueryError	Error codes for map query operations.
OperationError	Generic error codes for runtime operations without operation-specific failure modes.
PixelCoordinates	Pixel coordinates.

Functions

Name	Description
queryMapIntersection	Query the map intersection point for a given horizontal location.
queryMapIntersection	Convenience overload for Geodetic position directly in return type.
queryMapIntersection	Convenience overload for ECEF position directly in return type.
queryMapIntersection	Query the map intersection point along a ray.
queryMapIntersection	Convenience overload for Geodetic position directly in return type.
queryMapIntersection	Convenience overload for ECEF position directly in return type.
queryMapIntersection	Query map intersection points for a set of image pixels given pose and lens.
queryMapIntersection	Convenience overload for ECEF pose with ECEF positions in return type.
queryMapIntersection	Convenience overload for Geodetic pose with Geodetic positions in return type.
renderMap	Render the loaded 3D map from a given camera viewpoint.
renderMapCoverage	Render a map coverage mask for a given camera viewpoint.
computeFeatureDensity	Computes the feature density of an input image.

---

Error types for runtime operations

MapQueryError

enum class MapQueryError : std::uint8_t

MapQueryError Error codes for map query operations.

Describes different errors that may occur when querying the map.

InsufficientMapCoverage : Insufficient 3D map coverage at the query location - location is likely outside map bounds

InvalidInput : Operation could not be performed due to invalid input

InvalidLicense : Operation could not be performed due to an invalid or insufficient license

Failed : Operation failed due to errors

---

OperationError

enum class OperationError : std::uint8_t

Generic error codes for runtime operations without operation-specific failure modes.

InvalidLicense : Operation could not be performed due to an invalid or insufficient license

Failed : Operation failed due to errors

---

Map intersection queries

PixelCoordinates

struct PixelCoordinates

Pixel coordinates.

Fractional representation of pixel coordinates. [0,0] marks the upper-left corner of the upper-left pixel in the image. [width, height] marks the lower-right corner of the lower-right pixel. Sampling outside the image is an error.

Variables

Name	Description
x	X position of pixel.
y	Y position of pixel.

Variable Details

x

double x

X position of pixel.

y

double y

Y position of pixel.

---

Function Details

queryMapIntersection

Function

std::variant<Position, MapQueryError> queryMapIntersection( Context& context, const Position& position) noexcept

Query the map intersection point for a given horizontal location

Returns the 3D point on the map surface at the specified horizontal location. Parameters:

• context - Raptor SDK context. Must outlive the call.
• position - The query position (see Position type for format details) Returns: std::variant containing either:
  • Position: The map intersection point at the query location
  • MapQueryError: Error code if the query failed

note

This does not necessarily return the ground level point, rather it returns the point of the map surface. For example, if the map contains a building or trees at the given horizontal location, the point of the top of the building or tree is returned.

See: MapQueryError for possible error conditions

Function

std::variant<position::Geodetic, MapQueryError> queryMapIntersection( Context& context, const position::Geodetic& position) noexcept

Convenience overload for Geodetic position directly in return type

Function

std::variant<position::Ecef, MapQueryError> queryMapIntersection( Context& context, const position::Ecef& position) noexcept

Convenience overload for ECEF position directly in return type

Function

std::variant<Position, MapQueryError> queryMapIntersection(Context& context, const Ray& ray) noexcept

Query the map intersection point along a ray

Returns the 3D point on the map surface where the given ray (origin + direction) first hits. Parameters:

• context - Raptor SDK context. Must outlive the call.
• ray - The ray to intersect with the map (see Ray type for format details) Returns: std::variant containing either:
  • Position: The map intersection point
  • MapQueryError: Error code if the query failed

note

This does not necessarily return the ground level points, rather it returns the points of the map surface. For example, if the map contains a building or trees at the intersection point, the point of the top of the building or tree is returned.

See: MapQueryError for possible error conditions

Function

std::variant<position::Geodetic, MapQueryError> queryMapIntersection( Context& context, const ray::Geodetic& ray) noexcept

Convenience overload for Geodetic position directly in return type

Function

std::variant<position::Ecef, MapQueryError> queryMapIntersection( Context& context, const ray::Ecef& ray) noexcept

Convenience overload for ECEF position directly in return type

Function

std::vector<std::variant<Position, MapQueryError>> queryMapIntersection( Context& context, const LensModel& lens, const Pose& pose, std::span<PixelCoordinates> pixelCoordinates) noexcept

Query map intersection points for a set of image pixels given pose and lens

For each pixel coordinate, casts a ray from the camera position through the pixel using the lens model and pose, and returns the 3D point on the map surface where the ray hits. Parameters:

• context - Raptor SDK context holding 3D maps and GPU resources. Must outlive the call.
• lens - Lens model parameters (see LensModel type for details)
• pose - The camera pose (see Pose type for format details)
• pixelCoordinates - Pixel XY-coordinates. Coordinates must be enclosed within the image. Returns: A vector with one entry per input pixel, each entry being either:
  • Position: The map intersection point for that pixel
  • MapQueryError: Error code if the per-pixel query failed

note

This does not necessarily return the ground level points, rather it returns the points of the map surface. For example, if the map contains a building or trees at the intersection point, the point of the top of the building or tree is returned.

See: MapQueryError for possible error conditions.

Function

std::vector<std::variant<position::Ecef, MapQueryError>> queryMapIntersection( Context& context, const LensModel& lens, const pose::Ecef& pose, std::span<PixelCoordinates> pixelCoordinates) noexcept

Convenience overload for ECEF pose with ECEF positions in return type

Function

std::vector<std::variant<position::Geodetic, MapQueryError>> queryMapIntersection( Context& context, const LensModel& lens, const pose::Geodetic& pose, std::span<PixelCoordinates> pixelCoordinates) noexcept

Convenience overload for Geodetic pose with Geodetic positions in return type

renderMap

Function

std::variant<Image, OperationError> renderMap(Context& context, const LensModel& lens, const Pose& pose) noexcept

Render the loaded 3D map from a given camera viewpoint

The rendered map can be used to manually validate the input to the pose estimation function. Parameters:

• context - Raptor SDK context. Must outlive the call.
• lens - Lens model parameters (see LensModel type for details)
• pose - Pose (see Pose type for format details) Returns: std::variant containing either:
  • Image: A grayscale image rendered from the 3D map matching the input pose
  • OperationError: Error code on failure

renderMapCoverage

Function

std::variant<Image, OperationError> renderMapCoverage(Context& context, const LensModel& lens, const Pose& pose) noexcept

Render a map coverage mask for a given camera viewpoint

The coverage mask indicates which pixels in the rendered view are covered by the loaded 3D map data. Parameters:

• context - Raptor SDK context. Must outlive the call.
• lens - Lens model parameters (see LensModel type for details)
• pose - Pose (see Pose type for format details) Returns: std::variant containing either:
  • Image: An 8-bit grayscale image where 0x00 marks no coverage and 0xFF marks coverage
  • OperationError: Error code on failure

computeFeatureDensity

Function

std::variant<float, OperationError> computeFeatureDensity(Context& context, ImageView image) noexcept

Computes the feature density of an input image

Returns a value in the range [0, 1] indicating the feature density of the input image. The feature density is computed as the ratio of the number of detected features to the total number of pixels in the image. Parameters:

• context - Raptor SDK context. Must outlive the call.
• image - Image (see ImageView type for format details). Returns: std::variant containing either:
  • float: Feature density in the range [0, 1] on success
  • OperationError: Error code on failure