Chameleon Work Flow
Introduction
This section describes how to create scenarios for simulation. Creation of scenarios begins in the zookeeper tool (you can find a detailed user guide here Zoo Keeper) and is completed in the chameleon editor. Scenarios are created by combining a scene with assets and defining actions that occur over the course of the simulation.
Creating a scenario
Before you start using the Chameleon editor to create your scenario you first use zookeeper to load the scene and assets to populate that scenario.
Installing scenes
Scenes are accessible from the 'Scenes' tab of zookeeper (Fig.1 - 1). All scenes you have access to will be shown with an indication whether they are installed or not. Chameleon can only load scenes that are stored locally so if the scene you want is not already downloaded, click its download button (Fig.1 - 2).
Note: you may need to check the version of the Editor you are using is compatible with the scene you want to use.
Fig. 1 Zoo Keeper - Chameleon
- Sidebar
- Chameleon main menu
- Scenarios
- Scenes
- Assets
- Report an issue button - opens your default email application to report an issue
- Assets
- Asset title
- Data released
- Asset category
- Download asset
- Scenario
- Number of assets use in the scenario
- Number of images created in a dataset
- Date scenario was created
- Version of Chameleon the scenario was created in
- Scenario title
- Categories of assets used in the scenario
- Scenarios scene
- Simulation script currently being used
- Edit button - open scenario in the editor
- Preview button - open scenario in the simulator as see a preview of the scenario
- Create dataset - open the scenario in the simulator and capture the images
- More button
- More
- Simulator template dropdown - change the current simulator template
- Update button - attempt to update the version of chameleon the scenario can be open in
- Download assets button - download all assets used in the scenario
- Scene
- Date scene as released
- Scene version
- Create a new scenario button - creates a new scenario using this scene
- Download button
Installing scenes
Any scenes you wish to use as a setting for a scenario needs to be download before starting Chameleon.
- Start by click on the Scenes option in the left hand sidebar
- All the scenes that are available to you will be shown here. Find the one you want to use and click on the download button
- The button is replaced by a loading bar. Please wait until the scene has fully downloaded before trying to create a new scenario
Installing assets
To use the Chameleon you will need to download at least one camera type. We also recommend downloading the Waypoint, the generator, the attractor and the destructor.
- Start by clicking on the Assets option in the left hand sidebar
- All the assets available to you will be shown here. To download an asset click on the assets download button
- Please wait until each asset has downloaded before starting the next one
Creating a scenario
You are now ready to create your scenario. This document isn't going to go into the process of creating a scenario but we do have a quick start guide and you will find documentation on all the tools included in the editor here.
Creating a dataset
Datasets are created by passing your scenario to the simulator along with a simulator template file that defines the simulation parameters, what output data to create and where to send it.
Database Output Path
Each chameleon simulator run creates a new dataset in a location. The default for this location is set in the Zookeeper setting (Fig.2 - 1) under the Database Output Path (Fig.2 - 3). This is a global path setting where all datasets will be stored. It must be a fully qualified path name, that can be inputted by a user or navigated to using the folder button (Fig.2 - 5). Once a new path has been selected in needs to be saved (Fig.2 - 4).
Fig.2 Zookeeper settings - Database Output Path
- Sidebar
- Settings menu item
- Locations
- Location title
- Selected folder location
- Save new location
- Select a folder button
User Data Path
The user data path and descriptor path are set in the simulator template editor in chameleon.
Fig.3 Simulator template settings
Each simulator template has its own output path relative to Database Output Path (Fig.3 - 1). This is the User Data Path which can be set in the Output settings section of the simulator template editor.
This can be used to keep the output of each template separate or to organize the outputs into projects at the user's choice.
Descriptor Path
Each time the simulator is run using this template, a new folder is created in User Data Path using the path defined in Descriptor Path (Fig.3 - 2) for that template.
Repeated runs of the simulator using this template with the same Descriptor Path will create new version - incremented folders to hold the new dataset. EG: the first run of the simulator will create a Descriptor_Path folder and subsequent runs will create Descriptor_Path_1, Descriptor_Path_2 and so on as shown.
The Dataset
Fig.3 Mindtech data structure
Inside the Descriptor_Path folder(s), the simulator will create the dataset for this run of the simulation template. The first level contains a dataset.hafds.json file containing a description of the dataset structure; a scenario_name.sco file where scenario_name is the name given to the scenario in the scenario editor and a folder named 'dataset' which will contain the dataset created from that scenario.
Note: in this example the Descriptor path has been given the same name as the scenario but this is not necessary if a different naming scheme is appropriate.
Camera Views
Each camera placed into the scenario produces its own view into the scene and records it into a folder named after the camera. Cameras are named in the scenario editor and can be given descriptive names or can take the default name. Multiple cameras with the same name will be given a numerical subscript to distinguish them from each other. This level also contains a spec.hafs.json file that contains a description of the annotations format (annotations are in the next level down)
Data Folders
Inside each camera folder chameleon will create an annotations file in csv format, a keypoints annotations file in json format and a subfolder for each of the images, masks, segments, normals and distances datasets.
Data Formats
Chameleon outputs a variety of annotations, described here.
RGB Images
An uncompressed .PNG format image is stored for each capture in the /images folder. The filenames are set by the simulator using the format:
image_<xDimension>x<yDimension>_<YYYY>-<MM>-<DD>_<HH>-<MM>-<SS>-<ss>_<NNNN>.png
Where x and y dimensions are in pixels, date/time value is the actual capture time of the first captured image of the sequence and NNNN is the number of the image in the sequence.
Distances
When selected in the simulation template, a distances file is written out for each image to the /distances folder. The files are named by the simulator using the format:
distance_<xDimension>x<yDimension>_<YYYY>-<MM>-<DD>_<HH>-<MM>-<SS>-<ss>_<NNNN>.hdf
Where x and y dimensions are in pixels, date/time value is the actual capture time of the first captured image of the sequence and NNNN is the number of the image in the sequence.
The file is in binary format and contains the world space distance vector in metres, expressed as three single precision floating point numbers, from the camera to the object surface visible in each pixel position of the image.
Masks
When selected in the simulation template, a masks file is written out for each image to the /masks folder. The files are named by the simulator using the format:
mask_<xDimension>x<yDimension>_<YYYY>-<MM>-<DD>_<HH>-<MM>-<SS>-<ss>_<NNNN>.hmf
Where x and y dimensions are in pixels, date/time value is the actual capture time of the first captured image of the sequence and NNNN is the number of the image in the sequence.
The file is in binary format and contains the unique ID number, expressed as an integer, of the object visible in each pixel position of the image. The unique ID references objects in the annotations file for this camera. Only object classes that are tracked in the scenario can be referenced in this way.
Normals
When selected in the simulation template, a normals file is written out for each image to the /normals folder. The files are named by the simulator using the format:
normal_<xDimension>x<yDimension>_<YYYY>-<MM>-<DD>_<HH>-<MM>-<SS>-<ss>_<NNNN>.hnf
Where x and y dimensions are in pixels, date/time value is the actual capture time of the first captured image of the sequence and NNNN is the number of the image in the sequence.
The file is in binary format and contains the normalized world space surface normal vector, expressed as three single precision floating point numbers, of the object surface visible in each pixel position of the image.
Segments
When selected in the simulation template, a segments file is written out for each image to the /segments folder. The files are named by the simulator using the format:
segment_<xDimension>x<yDimension>_<YYYY>-<MM>-<DD>_<HH>-<MM>-<SS>-<ss>_<NNNN>.png
Where x and y dimensions are in pixels, date/time value is the actual capture time of the first captured image of the sequence and NNNN is the number of the image in the sequence.
The file is in .png format and contains the segmented image. Object segmentation colors are allocated in the scenario editor with unallocated objects defaulting to black. All objects with a segment color allocated in the scenario are rendered in the segment image even if they are not tracked in the annotations file.