Skip to content
Sodero Docs
Sodero Docs Sodero Docs

    Create a Map from Your Site

    Stellar Station does not build maps on the robot; there is no SLAM. You make the map bundle of your site beforehand, from a 3D model or a 3D scan of the site, and then upload it as described in Load and Configure a Map. Every file and key of the bundle is specified in Map Bundle Format.

    The Localizer matches the camera's depth images against the 3D point cloud of the bundle to find the robot on the map. The Navigator plans paths on the 2D occupancy grid. Both describe the same site in the same coordinates.

    Any point-cloud tool, such as CloudCompare or Open3D, can do the steps below.

    1. Choose the Coordinate Frames

    Choose the map frame of your site: x and y horizontal, z up, the floor at z = 0, in meters. All frames, and why the camera height is measured from the floor, are explained in Localization and Navigation › Coordinate Frames.

    2. Get a Point Cloud

    Collect points on every surface the camera will see, in the map frame of step 1:

    • 3D model: sample points on the surfaces of the site's model, for example the USD world of your Isaac Sim scene, with normals and colors where available. When the map frame is the world frame, poses in the simulator and on the map are the same.
    • 3D scan: scan the real site with a laser scanner or by photogrammetry, and level the scan so that the floor lies at z = 0.

    3. Clean and Export the PLY

    1. Remove people, vehicles and other objects that move, stray points and everything outside the site.
    2. Downsample to a point spacing of 2 to 5 cm, at most 2 million points; the Localizer reduces the map to map.voxel_size (5 cm by default) anyway.
    3. Export a binary little-endian PLY with float x, y, z, optional normals and uchar colors: points only, no faces and no extra fields (Point Cloud).

    4. Make the Occupancy Grid

    1. Pick the resolution (typically 0.05 m) and a rectangle that covers the cloud with a margin. Its lower-left corner is the origin; width and height are its size divided by the resolution, rounded up.
    2. Mark a cell occupied (0) when it holds points in the height band the robot can hit, from just above the floor to just above the robot, for example 0.05 to 0.65 m.
    3. Mark a cell free (254) when it holds floor points and no obstacle, and every other cell unknown (205).
    4. Write the PGM with its top row at the largest y, then the grid YAML (Occupancy Grid). Record the height band in meta.yaml as z_slice.

    Tip: Compare the PGM with a top view of the point cloud. The walls must line up; a grid mirrored top to bottom was written bottom row first.

    5. Write the YAML Files

    Choose a map ID, name the three map files after it, and write the five YAML files: meta.yaml, localizer.yaml, navigator.yaml, extrinsics.yaml and initial_pose.yaml (Files). Copy the width, height, resolution and origin of the grid into meta.yaml without rounding.

    Start navigator.yaml from the file of a working bundle, such as the warehouse example of Navigate in Simulation, and change values only.

    6. Measure the Camera Mounting

    Measure the camera's optical center from base_link: x forward and y left from the base origin, z up from the floor. Measure its downward tilt and take the quaternion from extrinsics.yaml. Set camera_frame_id and the edge's child to the camera node's frame_id.

    7. Pack the Bundle

    # build/site.nav/ holds the five YAML files and map/
tar -czf site.nav.tgz -C build site.nav   # file for the Station page
cp site.nav.tgz site.nav                  # the same file, named for sodero maps upload
tar -tzf site.nav                         # every entry starts with site.nav/

    Do not pack with tar -czf site.nav.tgz -C build/site.nav .: the ./ entry it adds is refused. Archive entries with hidden names, such as files some archivers add on macOS, are refused too.

    8. Check the Bundle

    The Station page checks the archive's layout when you upload it. The CLI preview checks every rule of the format without changing anything, so preview a new bundle from the SSH workspace first:

    sodero navigation get --node sodero.localizer                           # note "sha256"
sodero maps upload site.nav --node sodero.localizer --if-sha256 SHA256  # preview only, without --execute

    The preview reports the first problem it finds (Validation Errors).

    Checklist

    • The map frame has the floor at z = 0, and the point cloud and the grid use the same coordinates.
    • The grid files are map/MAP_ID.pgm and map/MAP_ID.yaml, and meta.yaml repeats their width, height, resolution and origin exactly.
    • The PLY holds only x, y, z with optional normals and colors, and at most 2 million points.
    • The grid YAML has exactly six keys, negate is 0 or 1, and free_thresh is below occupied_thresh.
    • camera_frame_id matches the camera node's frame_id, the edges use quat [x, y, z, w], and the camera height is measured from the floor.
    • initial_pose.yaml gives the pose of base_link, with yaw in radians.
    • navigator.yaml is complete, with your robot's robot_radius and speed limits.
    • The archive is a gzip tar with one top folder, at most 64 MiB, and the CLI preview reports no problem.
    • In simulation, the localization status reaches Healthy and the robot reaches a nearby goal before you drive the real robot.

    Then upload the bundle: Load and Configure a Map.