Skip to content
Intrepid AI Docs

Intrepid Simulator API [map]

API Reference - map

This module allows you to create a map, spawn objects or vehicles, and perform map queries (get closest object, get objects in the area, etc.).

Spawning objects

map.spawn(object_definition)

Spawns GLTF object on the map. Currently, all GLTF objects are loaded from assets directory and need to have all meshes to be a named a certain way.

List of available objects that come with the simulator:

  • buildings/building1.glb
  • buildings/building2.glb
  • buildings/building31.glb
  • buildings/building32.glb
  • trees/tree_a.glb
  • trees/tree_b.glb

Object definition is a table with the following fields:

  • mesh (string) - path to the GLTF object (see above)
  • position (vec3, optional) - position of the object on the map, in local coordinates (X, Y, Z)
  • rotation (bivec3, optional) - rotation of the object on the map, roll-pitch-yaw (YZ, ZX, XY)
  • scale (f32, optional) - scale of the object
await client.rpc('map.spawn', {
    mesh: 'trees/tree_a.glb',
    position: { x: 1.5, y: 0 },
    rotation: { yz: 0.1, zx: 0, xy: 0 },
})

map.spawn_uav(robot_definition)

Spawns aerial vehicle on the map.

Robot definition is a table with the following fields:

  • robot_id (u32) - unique identifier of the robot
  • position (vec3, optional) - position of the robot on the map, in local coordinates (X, Y, Z)
  • rotation (bivec3, optional) - rotation of the robot on the map, roll-pitch-yaw (YZ, ZX, XY)
await client.rpc('map.spawn_uav', {
    robot_id: 1,
    position: { x: 0, y: 1 },
    rotation: { yz: 0, zx: 0, xy: 0 },
})

map.spawn_ugv(robot_definition)

Spawns ground vehicle on the map. See map.spawn_uav for details about robot definition.

await client.rpc('map.spawn_ugv', {
    robot_id: 2,
    position: { x: 0, y: -1 },
    rotation: { yz: 0, zx: 0, xy: 0 },
})

map.spawn_urdf(urdf_robot_definition)

Loads robot from URDF file and spawns it on the map.

URDF Robot definition is a table with the following fields:

  • robot_id (u32) - unique identifier of the robot
  • position (vec3, optional) - position of the robot on the map, in local coordinates (X, Y, Z)
  • rotation (bivec3, optional) - rotation of the robot on the map, roll-pitch-yaw (YZ, ZX, XY)
  • urdf_path (string) - path to the URDF file
  • mesh_dir (string) - path to the directory with STL files
await client.rpc('map.spawn_urdf', {
    robot_id: 3,
    position: { x: 10, y: 0 },
    rotation: { yz: 0, zx: 0, xy: 0 },
    urdf_path: 'flamingo_edu/urdf/Edu_v4.urdf',
    mesh_dir: 'assets/flamingo_edu/urdf',
})

map.spawn_goal(goal_definition)

Spawns a goal (visual marker on the map) that toggles its state when a robot enters its vicinity.

Goal definition is a table with the following fields:

  • position (vec3, optional) - position of the goal on the map, in local coordinates (X, Y, Z)
  • rotation (bivec3, optional) - rotation of the goal on the map, roll-pitch-yaw (YZ, ZX, XY)
  • radius (f32, optional) - radius of the goal (default: 1)
  • height (f32, optional) - height of the goal (default: 2)
  • active (bool, optional) - initial state of the goal (active or not, default: true)
await client.rpc('map.spawn_goal', {
    position: { x: 0, y: 0, z: 0 },
})

map.spawn_road(road_definition)

Adds a road segment to the road network.

Road definition is a table with the following fields:

  • src (vec2) - start point of the road segment, in local coordinates (X, Y)
  • dst (vec2) - end point of the road segment, in local coordinates (X, Y)
  • highway (bool, optional) - whether the road is a highway (currently unused)
await client.rpc('map.spawn_road', {
    src: { x: 0, y: 0 },
    dst: { x: 10, y: 10 },
})

map.spawn_camera(camera_definition)

Creates a camera object in the simulator.

Camera definition is a table with the following fields:

  • position (vec3, optional) - position of the camera on the map, in local coordinates (X, Y, Z)
  • rotation (bivec3, optional) - rotation of the camera on the map, roll-pitch-yaw (YZ, ZX, XY)
  • size (vec2, optional) - size of the camera image (X, Y, in pixels, default: 768x576)
  • fov (f32, optional) - field of view of the camera in radians (default: PI/4)
  • format (string, optional) - mime-type of the received images (default: image/tiff)
  • parent (string, optional) - ID of the parent object to attach the camera to, static camera if not set
  • depth_camera (bool, optional) - make this camera a depth camera instead of rgb

Camera can be attached to a vehicle (moving with it) or be static. To attach a camera to a vehicle, set parent field to that vehicle’s ID.

Format is a mime-type corresponding to the image format. Currently supported formats are:

  • image/tiff (default)
  • image/png
  • image/jpeg
  • image/webp
  • image/bmp

Note that formats like PNG and JPEG are slow to encode (up to a second for large sizes), that’s why TIFF is chosen as the default. If you’re getting just one image, PNG is fine, but if you want images faster than 1Hz, consider using TIFF.

You can switch camera to show depth instead of RGB image using depth_camera field. In this mode, the camera outputs pixel data where the hue and brightness represent the distance from camera to the object (red/bright is close, blue/dark is far). This mode is not yet configurable and is considered to be work-in-progress.

let camera_rgb = await client.rpc('map.spawn_camera', {
    position: { x: 0, y: 0, z: 0 },
    rotation: { yz: 0, zx: 0, xy: 0 },
    size: { w: 768, h: 576 },
    parent: 'HAAAAAEAAAA=',
    fov: Math.PI / 4,
    format: 'image/png',
})

Getting all objects

map.list_objects()

Returns a table with all spawned objects on the map. Key is object ID, value is a table with object properties. You can use ID to query and set object state (see object module).

let objects = await client.rpc('map.list_objects')
// or subscribe
let sub = client.newSubscription('map.list_objects')

Object properties is a table with one field - type (string). Object types are ground, obstacle, vehicle, goal. Example:

Work in progress

Object types are ground, obstacle, vehicle, goal.

map.list_vehicles()

Returns a table with all spawned vehicles on the map. Key is vehicle ID, value is a table with vehicle properties. You can use ID to query and set object state (see object module).

let vehicles = await client.rpc('map.list_vehicles')
// or subscribe
let sub = client.newSubscription('map.list_vehicles')

Vehicle properties is a table with one field - robot_id (u32). Example:

Work in Progress

Working with GPS coordinates

This module allows you to convert between global (GPS) and local (ENU) coordinates, as well as set GPS origin for local coordinates.

map.gps_to_enu(gps_coords)

Converts GPS coordinates to local ENU coordinates.

let enu_coords = await client.rpc('map.gps_to_enu', { lat: 50.844968, lon: 4.363814, alt: 0 })

Return value is a table with three fields - x (f32), y (f32), z (f32).

map.enu_to_gps(enu_coords)

Converts local ENU coordinates to GPS coordinates.

let gps_coords = await client.rpc('map.enu_to_gps', { x: 1, y: 2, z: 3 })

Return value is a table with three fields - lat (f32), lon (f32), alt (f32).

map.set_zero(gps_coords)

Sets GPS origin for local ENU coordinates.

await client.rpc('map.set_zero', { lat: 50.844968, lon: 4.363814, alt: 0 })

Spatial queries

This module allows you to perform spatial queries on the map, such as finding nearest object, finding objects in a certain area, or performing raycasts.

map.find_nearest(params)

Finds the nearest object to a given point.

Parameters is a table with the following fields:

  • point (vec3) - point to check
  • solid (bool) - whether objects are considered hollow or solid (default: false)
  • groups (string[]) - list of object groups to include (default: all)
  • exclude (string[]) - list of object IDs to exclude from search
  • anchor (objectid) - use this object as a reference point instead of world center

If solid is set to true, all collider shapes are considered to be solid (so all queries and raycasts originating from inside of a solid shape will return the point itself). If it is set to false, all collider shapes are considered to be hollow (so all queries and raycasts originating from inside of a hollow shape will stop at that shape’s boundary).

groups is a list of object groups to include in the search. If not set, all objects are included. Currently available groups are: terrain, obstacle, vehicle, goal.

let nearest = await client.rpc('map.find_nearest', {
    point: { x: 0, y: 0, z: 10 },
    groups: ['terrain', 'obstacle'],
})

Returns a table with the following fields:

  • entity (string) - ID of the nearest object
  • group (string) - group of the nearest object
  • point (vec3) - coordinates of the nearest point
  • is_inside (bool) - whether the point is inside the object

Example:

Work in progress

map.intersection_with_aabb(params)

Finds all objects intersecting with a given AABB (axis-aligned bounding box).

Parameters is a table with the following fields:

  • center (vec3) - center of the AABB
  • half_extents (vec3) - half extents of the AABB
  • anchor (objectid) - use this object as a reference point instead of world center
let intersections = await client.rpc('map.intersection_with_aabb', {
    center: { x: 0, y: 0, z: 0 },
    half_extents: { x: 1, y: 1, z: 1 },
})

Returns a list of objects inside AABB. Each result is a table with the following fields:

  • entity (string) - ID of the object
  • group (string) - group of the object

Example:

let intersections = await client.rpc('map.intersection_with_aabb', {
    center: { x: 0, y: 0, z: 0 },
    half_extents: { x: 1, y: 1, z: 1 },
})

The example above would return all objects that touch the AABB (which in this case is a cube located at the origin with size 2x2x2).

map.intersection_with_point(params)

Finds all objects that contain a given point.

Parameters is a table with the following fields:

  • point (vec3) - point to check
  • groups (string[]) - list of object groups to include (default: all), see map.find_nearest for details
  • exclude (string[]) - list of object IDs to exclude from search
  • limit (u32) - maximum number of objects to return
  • anchor (objectid) - use this object as a reference point instead of world center
Work in progress

Returns a list of objects that contain the point. Each result is a table with the following fields:

  • entity (string) - ID of the object
  • group (string) - group of the object

Example:

Work in progress

This particular example would usually return terrain (because negative altitude is set).

map.intersection_with_ray(params)

Finds all objects intersecting with a given ray, ordered by distance from the ray origin.

Parameters is a table with the following fields:

  • ray_origin (vec3) - origin of the ray
  • ray_dir (vec3) - direction of the ray
  • max_toi (f32) - maximum time of intersection (default: unlimited)
  • solid (bool) - whether objects are considered hollow or solid (default: false), see map.find_nearest for details
  • groups (string[]) - list of object groups to include (default: all), see map.find_nearest for details
  • exclude (string[]) - list of object IDs to exclude from search
  • limit (u32) - maximum number of objects to return
  • anchor (objectid) - use this object as a reference point instead of world center
let intersections = await client.rpc('map.intersection_with_ray', {
    ray_origin: { x: 0, y: 0, z: 10 },
    ray_dir: { x: 0, y: 0, z: -1 },
    groups: ['terrain', 'obstacle', 'vehicle'],
})

Returns a list of objects that intersect with the ray. Each result is a table with the following fields:

  • entity (string) - ID of the object
  • group (string) - group of the object
  • toi (f32) - time of impact of the ray with the object
  • normal (vec3) - normal at the intersection point

Contact point is not given, but you can compute it using ray_origin + ray_dir * toi.

Example: