viamcartographer

README

viam-cartographer

User documentation

For user documentation, see Cartographer Modular Resource.

(In)stability Notice

Warning This is an experimental feature. Stability is not guaranteed. Breaking changes are likely to occur, and occur often.

Overview

This repo wraps Cartographer as a modular resource so it is easily usable with the rest of Viam's ecosystem. Cartographer is a system that provides real-time Simultaneous Localization And Mapping (SLAM) in 2D and 3D across multiple platforms and sensor configurations.

Getting started

Stable AppImages

Install viam-cartographer:

• Linux aarch64:

  sudo curl -o /usr/local/bin/cartographer-module https://storage.googleapis.com/packages.viam.com/apps/slam-servers/cartographer-module-stable-aarch64.AppImage
  sudo chmod a+rx /usr/local/bin/cartographer-module
  

• Linux x86_64:

  sudo curl -o /usr/local/bin/cartographer-module https://storage.googleapis.com/packages.viam.com/apps/slam-servers/cartographer-module-stable-x86_64.AppImage
  sudo chmod a+rx /usr/local/bin/cartographer-module
  

• MacOS/Linux

  brew tap viamrobotics/brews && brew install cartographer-module
  

Note that AppImages require FUSE to run. See documentation.

Development

You can either install the latest AppImages for testing, or build the code from source.

Latest AppImages

You can install the latest AppImages using:

• Linux aarch64:

  sudo curl -o /usr/local/bin/cartographer-module https://storage.googleapis.com/packages.viam.com/apps/slam-servers/cartographer-module-latest-aarch64.AppImage
  sudo chmod a+rx /usr/local/bin/cartographer-module
  

• Linux x86_64:

  sudo curl -o /usr/local/bin/cartographer-module https://storage.googleapis.com/packages.viam.com/apps/slam-servers/cartographer-module-latest-x86_64.AppImage
  sudo chmod a+rx /usr/local/bin/cartographer-module
  

Note that AppImages require FUSE to run. See documentation.

Build from source

Download

git clone --recurse-submodules https://github.com/viamrobotics/viam-cartographer.git

If you happened to use git clone only, you won't see the cartographer folder and will need to fetch it:

git submodule update --init

(Optional) Using Canon Images

If desired, Viam's canon tool can be used to create a docker container to build arm64 or amd64 binaries of the SLAM server. The canon tool can be installed by running the following command:

go install github.com/viamrobotics/canon@latest

And then by running one of the following commands in the viam-cartographer repository to create the container:

canon -arch arm64

canon -arch amd64

These containers are set to persist between sessions via the persistent parameter in the .canon.yaml file located in the root of viam-cartographer. More details regarding the use of Viam's canon tool can be found here.

Setup, build, and run the binary

# Install dependencies using brew (or apt-get)
make setup
# Build
make build
# Install lua files and binaries to /usr/local
make install
# Run the binary
cartographer-module

Linting

make lint-setup
make lint

Testing

make build
make test

Working with submodules

Commit and push

1. Commit and push changes in the cartographer submodule first.
2. Commit and push changes in the viam-cartographer library last.

Or, alternatively:

1. Commit changes in the cartographer submodule
2. Commit changes in the main repo
3. Push all changes by running git push --recurse-submodules=on-demand

Changing branches in a submodule

When changing branches in a submodule, update .gitmodules, e.g., changing to a branch called kk/fix-install:

...
[submodule "viam-cartographer/cartographer"]
        path = viam-cartographer/cartographer
        url = git@github.com:kkufieta/cartographer.git
        branch=kk/fix-install

Commit & push the changes.

When pulling those changes, run the following:

git pull
git submodule update --init --recursive

Troubleshooting Build Failures

Protobuf errors

When building on MacOS and seeing errors related to protobuf such as

Undefined symbols for architecture arm64:
  "google::protobuf::internal::InternalMetadata::~InternalMetadata()", referenced from:
      google::protobuf::MessageLite::~MessageLite() in libviam-cartographer.a(common.pb.cc.o)
      google::protobuf::MessageLite::~MessageLite() in libviam-cartographer.a(slam.pb.cc.o)
      google::protobuf::MessageLite::~MessageLite() in libviam-cartographer.a(http.pb.cc.o)

or

/tmp/cartographer-module-20230421-29152-arkug3/viam-cartographer/../grpc/cpp/gen/google/api/http.pb.h:12:2: error: This file was generated by a newer version of protoc which is
/tmp/cartographer-module-20230421-29152-arkug3/viam-cartographer/../grpc/cpp/gen/google/api/http.pb.h:13:2: error: incompatible with your Protocol Buffer headers. Please update
/tmp/cartographer-module-20230421-29152-arkug3/viam-cartographer/../grpc/cpp/gen/google/api/http.pb.h:14:2: error: your headers.

Then it possible your brew installation is using the incorrect version of protobuf. To check if you are seeing this issue run

protoc --version

If your version is 3.20.3 then you may be having this error. To fix take the following steps

1. unlink protobuf@3

brew unlink protobuf@3

1. link normal protobuf

brew unlink protobuf && brew link protobuf

1. echo your path & confirm you are not manually pathing to protobuf@3. If you see protobuf@3 in your path, track down where that is being added to your path & remove it (try .zshrc / .bashrc)

echo $PATH

1. Create a new terminal window to get a clean shell state

2. Confirm you have a new version installed. The minimum version you should see on your Mac is 3.21.12

protoc --version

CMake error about CMakeCache.txt

If you see an error during make build like:

$ make build
Submodule found successfully
grep -q viam-patched viam-cartographer/cartographer/CMakeLists.txt || \
	(cd viam-cartographer/cartographer && git checkout . && git apply ../cartographer_patches/carto.patch)
buf generate --template ./buf/buf.gen.yaml buf.build/viamrobotics/api
buf generate --template ./buf/buf.grpc.gen.yaml buf.build/viamrobotics/api
buf generate --template ./buf/buf.gen.yaml buf.build/googleapis/googleapis
# Touch this file so that we don't regenerate the buf compiled C++ files
# every time we build
cd viam-cartographer && cmake -Bbuild -G Ninja -DCMAKE_PREFIX_PATH=/opt/homebrew -DQt5_DIR=/opt/homebrew/opt/qt@5/lib/cmake/Qt5 && cmake --build build
CMake Error: The current CMakeCache.txt directory /Users/eshamaharishi/Documents/code/viam-cartographer/viam-cartographer/build/CMakeCache.txt is different than the directory /host/viam-cartographer/build where CMakeCache.txt was created. This may result in binaries being created in the wrong place. If you are not sure, reedit the CMakeCache.txt
CMake Error: The source "/Users/eshamaharishi/Documents/code/viam-cartographer/viam-cartographer/CMakeLists.txt" does not match the source "/host/viam-cartographer/CMakeLists.txt" used to generate cache.  Re-run cmake with a different source directory.

then you probably previously built for a different architecture. You should run make clean and then run make build again.

License

Copyright 2023 Viam Inc.

Apache 2.0 - See LICENSE file

Documentation

Overview

Package viamcartographer implements simultaneous localization and mapping. This is an Experimental package.

Index

• Constants
• Variables
• func CheckQuaternionFromClientAlgo(pose spatialmath.Pose, componentReference string, ...) (spatialmath.Pose, string, error)
• func InitCartoLib(logger logging.Logger) error
• func New(ctx context.Context, deps resource.Dependencies, c resource.Config, ...) (slam.Service, error)
• func TerminateCartoLib() error
• type CartographerService
  • func (cartoSvc *CartographerService) Close(ctx context.Context) error
  • func (cartoSvc *CartographerService) DoCommand(ctx context.Context, req map[string]interface{}) (map[string]interface{}, error)
  • func (cartoSvc *CartographerService) InternalState(ctx context.Context) (func() ([]byte, error), error)
  • func (cartoSvc *CartographerService) PointCloudMap(ctx context.Context, returnEditedMap bool) (func() ([]byte, error), error)
  • func (cartoSvc *CartographerService) Position(ctx context.Context) (spatialmath.Pose, string, error)
  • func (cartoSvc *CartographerService) Properties(ctx context.Context) (slam.Properties, error)
• type SubAlgo

Constants

const (

	// JobDoneCommand is the string that needs to be sent to DoCommand to find out if the job has finished.
	JobDoneCommand = "job_done"
	// SuccessMessage is sent back after a successful DoCommand request.
	SuccessMessage = "success"
	// PostprocessToggleResponseKey is the key sent back for the toggle postprocess command.
	PostprocessToggleResponseKey = "postprocessed"
)

Variables

var (
	Model = resource.NewModel("viam", "slam", "cartographer")

	// ErrClosed denotes that the slam service method was called on a closed slam resource.
	ErrClosed = errors.Errorf("resource (%s) is closed", Model.String())
	// ErrUseCloudSlamEnabled denotes that the slam service method was called while use_cloud_slam was set to true.
	ErrUseCloudSlamEnabled = errors.Errorf("resource (%s) unavailable, configured with use_cloud_slam set to true", Model.String())
	// ErrNoPostprocessingToUndo denotes that the points have not been properly formatted.
	ErrNoPostprocessingToUndo = errors.New("there are no postprocessing tasks to undo")
	// ErrBadPostprocessingPointsFormat denotest that the postprocesing points have not been correctly provided.
	ErrBadPostprocessingPointsFormat = errors.New("invalid postprocessing points format")
	// ErrBadPostprocessingPointsFormat denotest that the postprocesing points have not been correctly provided.
	ErrBadPostprocessingPath = errors.New("could not parse path to pcd")
)

Model is the model name of cartographer.

Functions

func CheckQuaternionFromClientAlgo

func CheckQuaternionFromClientAlgo(pose spatialmath.Pose, componentReference string,
	returnedExt map[string]interface{},
) (spatialmath.Pose, string, error)

CheckQuaternionFromClientAlgo checks to see if the internal SLAM algorithm sent a quaternion. If it did, return the updated pose.

func InitCartoLib

func InitCartoLib(logger logging.Logger) error

InitCartoLib is run to initialize the cartographer library must be called before module.AddModelFromRegistry is called.

func New

func New(
	ctx context.Context,
	deps resource.Dependencies,
	c resource.Config,
	logger logging.Logger,
	cartoFacadeTimeout time.Duration,
	cartoFacadeInternalTimeout time.Duration,
	testTimedLidarOverride s.TimedLidar,
	testTimedMovementSensorOverride s.TimedMovementSensor,
) (slam.Service, error)

New returns a new slam service for the given robot.

func TerminateCartoLib

func TerminateCartoLib() error

TerminateCartoLib is run to terminate the cartographer library.

Types

type CartographerService

type CartographerService struct {
	resource.Named
	resource.AlwaysRebuild

	SlamMode cartofacade.SlamMode
	// contains filtered or unexported fields
}

CartographerService is the structure of the slam service.

func (*CartographerService) Close

func (cartoSvc *CartographerService) Close(ctx context.Context) error

Close out of all slam related processes.

func (*CartographerService) DoCommand

func (cartoSvc *CartographerService) DoCommand(ctx context.Context, req map[string]interface{}) (map[string]interface{}, error)

DoCommand receives arbitrary commands.

func (*CartographerService) InternalState

func (cartoSvc *CartographerService) InternalState(ctx context.Context) (func() ([]byte, error), error)

InternalState creates a request, calls the slam algorithms InternalState endpoint and returns a callback function which will return the next chunk of the current internal state of the slam algo.

func (*CartographerService) PointCloudMap

func (cartoSvc *CartographerService) PointCloudMap(ctx context.Context, returnEditedMap bool) (func() ([]byte, error), error)

PointCloudMap creates a request calls the slam algorithms PointCloudMap endpoint and returns a callback function which will return the next chunk of the current pointcloud map.

func (*CartographerService) Position

func (cartoSvc *CartographerService) Position(ctx context.Context) (spatialmath.Pose, string, error)

Position forwards the request for positional data to the slam library's gRPC service. Once a response is received, it is unpacked into a Pose and a component reference string.

func (*CartographerService) Properties

func (cartoSvc *CartographerService) Properties(ctx context.Context) (slam.Properties, error)

Properties returns information regarding the current SLAM session including the mapping mode and is the session is being run in the cloud.

type SubAlgo

type SubAlgo string

SubAlgo defines the cartographer specific sub-algorithms that we support.

const Dim2d SubAlgo = "2d"

Dim2d runs cartographer with a 2D LIDAR only.