Cartographer - documentation, maintenance, tuning, tutorials?

Cartographer: we have a problem!

Dear ROS 1/2 programmers, engineers and enthusiasts!

Many of us use libcartographer and cartographer_ros package in our projects. This software provides satisfying quality of mapping and SLAM with modern sensory, it is flexible and able for tuning. The package is extremely popular in the community (more than 6k stars, 2k forks on Github!). But the package and library themselves look since 2021 poorly maintained and the worst fact - it is still undocumented! The online documentation is deprecated, so building the library now in 2023 is already not an easy task. The library is slowly becoming incompatible with developing APIs, such as AbseilCPP. Also, it is almost impossible to find the tuning tutorials, hacking examples and especially the library utilization instructions because the logic is very difficult to understand.

What can we do with it?

My suggestion to deal with the described problem is the following: let’s collect here under this topic the existing information about:

  • Experience in hacking Cartographer
  • Useful forks with feature descriptions
  • Tutorials
  • Parts of documentation for functions, APIs and integrations
  • Links to useful information
  • Descriptions of internal concepts, algorithms and principles used in the code (such as coordinate transformations).

Please feel free to share your opinions, experience and suggestions here!

Fork removing segmentation fault on C++17 and modern Eigen

As my initial small contribution, I am willing to present my fork of libcartographer, which removes segmentation faults when the library is compiled with recent Eigen3 and optimizing compiler, like Clang.

1 Like

WARNING: Opinionated rant. Feel free to ignore or dismiss

In believe that in robotics, Cartographer represent a mix of “Stockholm Syndrome” and “Sunk loss fallacy”.

Engineers must spend a ridiculous amount of time tuning parameters which are hard to understand, and see how they affect the result.
Once this long and iterative process is finally over, they look at their perfect map and say: “wow, Cartographer really works well”.

I personally think that a software that is so fragile and needs a lot of parameters tuning is not that great.

Said that, kudos to those people like @twetzel that are taking concrete actions to alleviate the existing issues.

1 Like

@facontidavide is there a better alternative?


the worst fact - it is still undocumented!

tuning parameters which are hard to understand

Aren’t you saying the same, i e. more documentation is needed to make it “easier to understand”?

For what it is worth, we’ve been releasing cartographer into Humble (and Rolling) from GitHub - ros2/cartographer: Cartographer is a system that provides real-time simultaneous localization and mapping (SLAM) in 2D and 3D across multiple platforms and sensor configurations. and GitHub - ros2/cartographer_ros: Provides ROS integration for Cartographer. . If there are fixes, I’ll suggest that we collect them in there, at least until/unless upstream becomes active again.

1 Like

@facontidavide is there a better alternative?


the worst fact - it is still undocumented!

tuning parameters which are hard to understand

Aren’t you saying the same, i e. more documentation is needed to make it “easier to understand”?

@JRTG I wanted to say that it is much better to have the parameters with descriptions about how they work, and also ANY documentation about the library API and functions available around the Protobuf structure they use.

1 Like

@clalancette for the library I will make a pull request there soon, but for ROS integration I still use ROS 1 version, this is also why I decided to discuss the problem here.

BTW, can you (or anyone here) explain briefly, which improvements did you do in the library?

I don’t want to derail this thread too far from Cartographer, as I’d like to see it make a comeback (despite how unwieldy it was to use), but in the meantime, for 2D SLAM at least, I’ve found slam_toolbox to be a well maintained and documented alternative:

Way back, my use case was for a small SBC platform with limited resources. Embedded computing power has of course improved sense 2017, but for general planar navigation, I’ve always preferred slam_toolbox to retain more headroom for CPU scheduling and other memory budgeting.


So in cartographer itself, very little. Mostly just updating the dependencies and the package.xml to properly declare dependencies.

For cartographer_ros, I did the initial port of it to ROS 2 back in 2017/2018. More recently, @doisyg did a substantial rework so we could update to cartographer 2. That is what we are shipping today.

As the author of SLAM Toolbox, I obviously have a bias towards it. But as I start most of my ROSCon talks with: if <the previous thing> worked super well, I wouldn’t have bothered making <this>. I’m not someone that desires to reinvent the wheel for tutorial exercise or “because I can”.

I really wanted to like and use Cartographer, but it was critically flawed in alot of ways and when I surveyed users, most that had good results also had exceptionally good odometry whereas any 2D SLAM system would work superbly and is less a reflection of Cartographer itself. The codebase is unwieldy, but to be totally fair to the authors, the paper describing it is exactly how I would have thought at that point in time about building a large-scale SLAM system. There are certainly redeeming qualities.

I’m definitely not going to turn around and say that SLAM Toolbox is perfect, that is something I worked on now approaching 5 years ago as an R&D project for a startup that accidentally turned out really good. But, it works very very well out of the box, because I spent the time to make sure that behavior worked well for a large number of vehicles and environments and provided well-tuned parameters that are a reasonable starting point. Its worth listening to the ROSCon 2019 talk on the subject.

Eventually, my hope is to start from ground-zero for a new SLAM and localization framework in ROS 2, but time will tell.

1 Like

Here is a wrap up of the full ros2 migration of the cartographer_ros package:

Due to the lack of maintainers at the time, we unfortunately could not merge in the original repos, that’s why the version used by the ros2 build farm are hosted on the ros2 org

1 Like

Thanks @facontidavide and @smac, it did not take long for the topic to drift toward cartographer alternatives debat :laughing:

Cartographer is indeed far from being perfect, complicated tune and to understand. I would love to see a proper replacement, however for my daily usage at Wyca and now at Dexory, it works. I haven’t checked SLAM toolbox for while, but for me the unmatched features of cartographer are :

  • the offline node that allows building a map from a bag at CPU speed (and which took most of my effort in the ros2 port)
  • saving and being able to re-open the pose graph (pbstream) for manipulation and editing. That’s essential for re-mapping and offers much more freedom than working from a bitmap

And in my experience, with admittedly lots of effort and a very, very, steep learning curve, it works impressively with crappy odometry.

However, I plead guilty of “sunk cost fallacy” on this one. There is a chance that I would have a different opinion if I had to start from scratch.

SLAM Toolbox has had that for a long time. Its not in their format, its in my format, but there are demo applications for map rotating and merging to show how you can use it.

We have the async mode for this :slight_smile: Its not quite the same thing, but meeting the same intent / need.

But again, I’m not interested or trying to debate the point. I wouldn’t have jumped in if someone else didn’t mention it. Just wanted to throw in my 2 cents and now backing away… there’s an actual topic that the initial poster wanted to discuss that has nothing to do with any of this convesation :slight_smile:

1 Like

I promise I would give it a new try once I will have a bit of time, but you run the risk of being hit with a couples of tickets.

@doisyg I started working on this problem (disassembling .pbstream) some time ago, but without significant progress. So, I would be VERY appreciated if you share somehow your work on this. Especially (and also I would want to kindly ask everyone here to share the knowledge) the coordinate transformation between submaps Cartographer does, should be documented, as I see. Till now, disassembling the pose graph, I am able to extract the submaps, but surprisingly, cannot still understand well, how the submap position could be scaled to re-assemble the map to build an editor…

Cartographer as a piece of software is fragile, you guys are all right in this aspect. But its potential for flexibility and localization quality makes sense when it comes to modular high-performance mapping. This is a good point to dig into and try to document the exploration of its internal API, no?

@ruffsl @clalancette @doisyg @JRTG to support a bit the discussion, could you please have a look at this gist:

Does someone know how to position the submaps in the field properly without cairo? I will be really very happy if I would be able to reassemble the map from submaps and then to document the coordinate transforms.