carla/Docs/tuto_A_add_props.md

Add new props

Props are the assets that populate the scene, besides the map, and the vehicles. That includes streetlights, buildings, trees, and much more. The simulator can ingest new props anytime in a simple process. This is really useful to create customized environments in a map.

• Prepare the package
  • Create the folder structure
  • Create the JSON description
• Ingestion in a CARLA package
• Ingestion in a build from source

---

Prepare the package

Create the folder structure

1. Create a folder inside carla/Import. The name of the folder is not relevant.

2. Create the subfolders. There should be one general subfolder for all the props, and inside of it, as many subfolders as props to import.

3. Move the files of each prop to the corresponding subfolder. A prop subfolder will contain the .fbx mesh, and optionally, the textures required by it.

For instance, an Import folder with two separate packages should have a structure similar to the one below.

Import
│
├── Package01
│   ├── Package01.json
│   └── Props
│       ├── Prop01
│       │   ├── Prop01_Diff.png
│       │   ├── Prop01_Norm.png
│       │   ├── Prop01_Spec.png
│       │   └── Prop01.fbx
│       └── Prop02
│           └── Prop02.fbx
└── Package02
    ├── Packag02.json
    └── Props
        └── Prop03
            └── Prop03.fbx

Create the JSON description

Create a .json file in the root folder of the package. Name the file after the package. Note that this will be the distribution name. The content of the file will describe a JSON array of maps and props with basic information for each of them.

Maps are not part of this tutorial, so this definition will be empty. There is a specific tutorial to add a new map.

Props need the following parameters.

• name of the prop. This must be the same as the .fbx.
• source path to the .fbx.
• size estimation of the prop. The possible values are listed here.
  • tiny
  • small
  • medium
  • big
  • huge
• tag value for the semantic segmentation. If the tag is misspelled, it will be read as Unlabeled.
  • Bridge
  • Building
  • Dynamic
  • Fence
  • Ground
  • GuardRail
  • Other
  • Pedestrian
  • Pole
  • RailTrack
  • Road
  • RoadLine
  • SideWalk
  • Sky
  • Static
  • Terrain
  • TrafficLight
  • TrafficSign
  • Unlabeled
  • Vegetation
  • Vehicles
  • Wall
  • Water

In the end, the .json should look similar to the one below.

{
  "maps": [
  ],
  "props": [
    {
      "name": "MyProp01",
      "size": "medium",
      "source": "./Props/Prop01/Prop01.fbx",
      "tag": "SemanticSegmentationTag01"
    },
    {
      "name": "MyProp02",
      "size": "small",
      "source": "./Props/Prop02/Prop02.fbx",
      "tag": "SemanticSegmentationTag02"
    }
  ]
}

!!! Warning Packages with the same name will produce an error.

---

Ingestion in a CARLA package

This is the method used to ingest the props into a CARLA package such as CARLA 0.9.8.

A Docker image of Unreal Engine will be created. It acts as a black box that automatically imports the package into the CARLA image, and generates a ditribution package. The Docker image takes 4h and 400GB to be built. However, this is only needed the first time.

1. Build a Docker image of Unreal Engine. Follow these instructions to build the image.

2. Run the script to cook the props. In the folder ~/carla/Util/Docker there is a script that connects with the Docker image previously created, and makes the ingestion automatically. It only needs the path for the input and output files, and the name of the package to be ingested.

python3 docker_tools.py --input ~/path_to_package --output ~/path_for_output_assets  --packages Package01

3. Locate the package. The Docker should have generated the package Package01.tar.gz in the output path. This is the standalone package for the assets.

4. Import the package into CARLA.

• On Windows extract the package in the WindowsNoEditor folder.

• On Linux move the package to the Import folder, and run the script to import it.

cd Util
./ImportAssets.sh

!!! Note There is an alternative on Linux. Move the package to the Import folder and run the script Util/ImportAssets.sh to extract the package.

---

Ingestion in a build from source

This is the method to import the props into a CARLA build from source.

The JSON file will be read to place the props inside the Content in Unreal Engine. Furthermore, it will create a Package1.Package.json file inside the package's Config folder. This will be used to define the props in the blueprint library, and expose them in the Python API. It will also be used if the package is exported as a standalone package.

When everything is ready, run the command.

make import

!!! Warning Make sure that the package is inside the Import folder in CARLA.

---

That is all there is to know about the different ways to import new props into CARLA. If there are any doubts, feel free to post these in the forum.

CARLA forum