CARLA Maps from Content Packs¶
A CARLA map the server does not ship -- a town cooked as a content pack -- is named by the pack that carries it. The framework downloads the pack, reads its HD map, mounts it on the server and runs the scenario on it, all through carla-pack-registry:
uv run scenario scenario=my_scenario/default \
map.name=NishishinjukuMap map.pack=tier4/carla-packs/NishishinjukuPack@1.2.0
Packs are shared through GitHub repository permissions: a pack repository
lists its packs in carla-packs.toml, and whoever can read that repository
can download them (straight from S3-compatible storage, or from a public
Hugging Face repository). There is no server to run. How to publish packs is
described in carla-pack-registry's own documentation.
Setting it up¶
Install the pack extra, and give carla-pack a GitHub token that can read the
pack repository:
pip install 'autoware-carla-scenario[pack]' # or: uv add carla-pack-registry
gh auth login # carla-pack uses the GitHub CLI's token as is
carla-pack whoami # who carla-pack reads the repositories as
carla-pack ls tier4/carla-packs # the packs you can download
The token is looked up as carla-pack looks it up: CARLA_PACK_TOKEN, then
GH_TOKEN, GITHUB_TOKEN, the one carla-pack login saved, and gh auth
token. In CI, pass a fine-grained token that can read the pack repository in
CARLA_PACK_TOKEN (a workflow's own GITHUB_TOKEN cannot read another
repository).
Naming the pack¶
map.pack takes one of two forms:
map.pack |
What is run |
|---|---|
OWNER/REPO/PACK@VERSION |
That version of the pack |
OWNER/REPO/PACK |
The newest version of the pack |
OWNER/REPO |
The newest pack in the repository providing map.name |
map.pack_sha256 pins the pack to one artifact, as a lock file would. Without
it, the run still mounts exactly the artifact its map files were read from:
the reference is resolved once, before the run, and its SHA-256 carried on.
A map group can name it once for every scenario:
# conf/map/nishishinjuku_pack.yaml
# @package _global_
map:
name: NishishinjukuMap
pack: tier4/carla-packs/NishishinjukuPack@1.2.0
What happens¶
- Before CARLA starts, the pack is downloaded into carla-pack's cache
(
~/.cache/carla-pack/blobs/<sha256>.tar.gz,CARLA_PACK_CACHE_DIR), verified against the repository manifest's SHA-256 and the pack's owncarla-pack.json, and unpacked there. Its map data is read by format: - the Lanelet2 map from the pack's
autowarefolder (the Lanelet2 map,map_projector_info.yamland the point cloud map), or else its barelanelet2map -- read asmap.directoryreads a directory; - the OpenDRIVE CARLA cooks the map from (
opendrive), which becomes the road network the run reads, so nothing has to be read back out of the loaded world.
A pack that carries no Lanelet2 map is still mounted; name the Lanelet2 map
with map.directory, map.source or map.lanelet2_path then.
2. Once the server is up -- the one the run starts, or one already
running -- the pack is installed into server.packs_dir and mounted on the
server, before the map is loaded. A pack already installed is not
downloaded again (the install is made from the same cached tarball), and
one already mounted is left as it is. A server the queue restarts after it
died mounts it again.
3. The map is loaded by map.name and the scenario runs as on any other map.
With map.pack=OWNER/REPO, a server that already has map.name (built in,
or mounted earlier) is used as it is, and nothing is mounted.
Precedence¶
| Setting | Wins over |
|---|---|
map.lanelet2_path, map.xodr_path |
everything below |
map.directory |
the pack's Lanelet2 map |
map.pack |
map.source |
map.source |
-- |
map.directory wins over the pack's Lanelet2 map only: the pack is still
mounted, and its OpenDRIVE is still read unless the directory ships one. A
batch's cases must agree on map.pack and map.pack_sha256, as they must on
every other map setting.
The trajectory log records the map's source as the pack the run read,
carla-pack:OWNER/REPO/PACK@VERSION -- the version included, also for
map.pack=OWNER/REPO or a pack named without one. When the pack carries no
Lanelet2 map and map.source gives it, the log names map.source instead.
map.pack_sha256 without map.pack is refused: there is nothing to pin.
Where packs are installed¶
The server reads a pack at the path it is installed at:
| Setting | Default |
|---|---|
server.packs_dir |
null |
AUTOWARE_CARLA_SCENARIO_PACKS_DIR |
-- |
| otherwise | ~/.autoware_carla_scenario/packs (AUTOWARE_CARLA_SCENARIO_HOME/packs) |
A relative path is taken from the working directory of the run and made
absolute before it is handed to the server. A blank server.packs_dir is
refused; null is the default.
A server on another machine (server.host) needs a directory it reads at the
same path as this machine -- a shared mount -- or the mount is refused. Each
installed pack takes its own size on disk, beside the cached tarball.
A multi-gigabyte pack is downloaded once; a dropped connection resumes where it stopped.
From Python¶
from autoware_carla_scenario import ScenarioQueue
from autoware_carla_scenario.maps import resolve_map_paths
from autoware_carla_scenario.maps.pack import MapPack
# Downloads and verifies the pack, and reads its Lanelet2 map and OpenDRIVE.
paths = resolve_map_paths(
{"name": "NishishinjukuMap", "pack": "tier4/carla-packs/NishishinjukuPack@1.2.0"}
)
queue = ScenarioQueue(
map_name=paths.name,
xodr_path=paths.xodr_path,
lanelet2_path=paths.lanelet2_path,
map_pack=MapPack(paths.pack, sha256=paths.pack_sha256),
)
queue.add(MyScenario(ego_config))
with queue: # starts CARLA, mounts the pack, loads the map
results = queue.run_all()
MapPack.files(map_name) alone hands back the pack's map files
(directory, xodr_path, and the resolved reference and sha256), and
MapPack.deploy(host, port, map_name) alone mounts the pack on a server.
Troubleshooting¶
When GitHub or the pack's storage refuses access, the run stops with a
PackAccessError (a MapPackError) that says what was refused, where the
token was taken from, and what to do. Its code is carla-pack's:
| Message | code |
Cause and fix |
|---|---|---|
GitHub authentication failed. No GitHub token was found ... |
unauthenticated |
No token in CARLA_PACK_TOKEN, GH_TOKEN, GITHUB_TOKEN, carla-pack login or gh auth token, and the repository is private: run gh auth login, or set CARLA_PACK_TOKEN |
GitHub authentication failed. GitHub rejected the token from <source> ... |
unauthenticated |
The token has expired or been revoked. The message names where it came from and how to renew it (gh auth login, carla-pack login, or the variable to set). A GitHub Actions workflow's own GITHUB_TOKEN cannot read another repository |
GitHub authentication failed. GitHub's limit on requests without a token ... |
unauthenticated |
The anonymous rate limit: give carla-pack a token |
access denied. OWNER/REPO does not exist, or the GitHub user <login> ... cannot read it |
no_access |
The token works but its user has no Read access to the pack repository (GitHub answers a private repository with not found): ask its owner for access, or use another user's token in CARLA_PACK_TOKEN |
the storage credentials of OWNER/REPO could not be read. Your GitHub access is fine ... |
credentials_unavailable |
The pack repository's read-only storage key expired: its credential workflow has to run (the owner's to fix) |
the pack's storage refused the download ... |
storage_error |
The storage key was rotated while downloading: retry |
carla-pack whoami shows which user and token carla-pack uses, and
carla-pack ls OWNER/REPO what it can read.
Other errors:
| Message | Cause |
|---|---|
Install carla-pack-registry to use map.pack |
The pack extra is not installed |
Could not find the pack ...: ... not found |
The pack or version does not exist in a repository you can read |
The pack ... does not carry the map ... |
map.name is not one of the pack's maps; the message lists them |
... did not mount the pack ... |
The server cannot read server.packs_dir at that path |
Could not deploy the pack ... with incompatible |
The pack was built for another CARLA release than the server's |