Configuration Settings

This section provides a comprehensive guide to configuring the GRID Enterprise. Understanding and correctly setting up these configurations is essential for using the platform.
Once you have successfully installed the sf-grid package, you can start configuring the GRID Enterprise by creating and modifying the necessary JSON configuration files.

Session Configuration

The session_config.json file defines the simulation and environmental settings for AirGen and GRID. This file includes everything from selecting the environment to configuring vehicles and camera setups.

Here is a baseline session configuration JSON:

{
  "airgen": {
    "env_name": "blocks",
    "geo": false,
    "settings": {
      "SimMode": "Multirotor",
      "Vehicles": {
        "Drone": {
          "VehicleType": "SimpleFlight",
          "VehicleModel": "Default"
        }
      }
    }
  },
  "grid": {
    "entities": {
      "robot": [{"name": "airgen-drone", "kwargs": {}}],
      "model": []
    }
  }
}

• env_name: Specifies the environment/scene which the simulation will start.
• geo: A boolean value indicating whether the environment is geospatial, meaning it uses real-world geographic coordinates.

AirGen Environments

The file name corresponding to the desired environment/scene is specified in env_name in the session configuration JSON. The following environments are currently available:

Urban Environments

Environment Name	File Name (without .tar.gz)
Abandoned Factory	abandoned_factory
City Block	city_block
Construction Site	construction_site
Electric Central	electric_central
Factory District	factory_district
Night City	night_city
Office Building	office_building
Parking Garage	parking_garage
Neighborhood	neighborhood

Remember to omit the .tar.gz extension when specifying the environment name in your JSON configuration.

Simulation Mode and Settings

Within the settings object, you define the mode of simulation and specific parameters for vehicles, cameras, and other simulation elements.

• SimMode: Defines the mode of simulation. Use "Multirotor" for drone simulations or "Car" for vehicle simulations.

• Vehicles: Defines the types and initial positions of vehicles in the simulation. Each vehicle’s behavior and appearance are controlled by the VehicleType and VehicleModel settings.

"Vehicles": {
  "Drone": {
    "VehicleType": "SimpleFlight",
    "VehicleModel": "Default",
    "X": 0, "Y": 0, "Z": 0
  }
}

• VehicleType: Specifies the type of vehicle. For drones, use "SimpleFlight"; for cars, use "Chaos."
• VehicleModel: Indicates the specific model of the vehicle.
• X, Y, Z: Defines the starting position of the vehicle in the simulation environment.

Please find the entire list of vehiclees supported in the AirGen sim here:

Aerial Vehicles

Vehicle Name	VehicleType	VehicleModel
Default	SimpleFlight	Default
Industrial Drone	SimpleFlight	Matrice300RTK
eVTOL	SimpleFlight	eVTOL
Freefly Alta X	SimpleFlight	AltaX
Freefly Astro	SimpleFlight	Astro
Agricultural Drone	SimpleFlight	IndustrialX4
Holybro S500	SimpleFlight	HolybroS500
ModalAI Starling 2 Max	SimpleFlight	Starling2Max

Multi-Agent Simulation

To instantiate multiple agents in the AirGen simulation, you can add multiple keys within the Vehicles category:

"Vehicles": {
  "Drone0": {
    "VehicleType": "SimpleFlight",
    "VehicleModel": "Default",
    "X": 0, "Y": 0, "Z": 0
  },
  "Drone1": {
    "VehicleType": "SimpleFlight",
    "VehicleModel": "Matrice300RTK",
    "X": -5, "Y": 0, "Z": 0
  },
  "Drone2": {
    "VehicleType": "SimpleFlight",
    "VehicleModel": "AltaX",
    "X": 5, "Y": 0, "Z": 0
  }
}

This starts a simulation with three different drones placed at their respective (X, Y, Z) locations.

Camera Settings

• CameraDefaults: Specify camera configuration, such as resolution and field of view.

"CameraDefaults": {
  "CaptureSettings": [
    { "ImageType": 0, "Width": 256, "Height": 256, "FOV_Degrees": 90 }
  ]
}

• ImageType: Specifies the type of image to be captured (e.g., scene, depth map).
• Width/Height/FOV_Degrees: Sets the resolution (width and height) and field of view (FOV) for the camera, affecting how much of the scene is captured.

Geographic Positioning

If geo is set to true, this setting specifies the starting geographic coordinates for the robot, critical for geospatial simulations.

"OriginGeopoint": {
  "Latitude": 47.62094998919241,
  "Longitude": -122.35554810901883,
  "Altitude": 100
}

• Latitude/Longitude/Altitude: Determines the initial placement of the robot in a geospatial context.

Camera Director Settings

These settings control the behavior and position of the third-person camera that follows the vehicle or robot during the simulation.

"CameraDirector": {
  "FollowDistance": -3,
  "X": 1, "Y": 0, "Z": 0,
  "Pitch": 0, "Roll": 0, "Yaw": 0
}

• FollowDistance: Determines the distance of the camera from the vehicle.
• X, Y, Z: Defines the exact position of the camera. If not set, the camera follows the vehicle dynamically.
• Pitch/Roll/Yaw: Controls the camera’s orientation in the simulation.

Camera Recording Configuration

Manages the settings related to camera recording within the simulation, allowing you to capture footage as the simulation runs.

"Recording": {
  "RecordOnMove": false,
  "RecordInterval": 0.05,
  "Folder": "",
  "Enabled": false,
  "Cameras": [
    { "CameraName": "0", "ImageType": 0, "PixelsAsFloat": false, "VehicleName": "", "Compress": true }
  ]
}

• RecordOnMove: If set to true, recording starts only when the vehicle or robot is moving.
• RecordInterval: Defines the time interval between consecutive frames.
• Folder: Specifies the directory where the recordings will be saved.
• Enabled: Toggles the recording feature on or off.
• Cameras: Lists the cameras involved in the recording, along with their specific settings.

External Camera Placement

Allows you to position fixed cameras within the simulation environment, which can capture footage independently of the vehicle’s movement.

"ExternalCameras": {
  "FixedCamera1": {
    // same elements as in CameraDefaults above
  },
  "FixedCamera2": {
    // same elements as in CameraDefaults above
  }
}

• FixedCamera 1/2: Specifies additional cameras with settings similar to CameraDefaults, allowing for multiple viewpoints within the simulation.

PhysicsEngineName

• Cars: Supports only PhysX.
• Multirotors: Supports FastPhysicsEngine and ExternalPhysicsEngine.
• ExternalPhysicsEngine: Allows the drone to be controlled via setVehiclePose(), useful for integration with external simulators or pre-defined paths.

ViewMode

The ViewMode determines which camera to use as default and how the camera will follow the vehicle.

• FlyWithMe: Chase the vehicle from behind with 6 degrees of freedom.
• GroundObserver: Chase the vehicle from 6’ above the ground with full freedom in the XY plane.
• Fpv: View the scene from the vehicle’s front camera.
• Manual: Manually control the camera with arrow keys and ASWD keys.
• SpringArmChase: Chase the vehicle with a camera mounted on an (invisible) arm attached to the vehicle via a spring, introducing latency in movement.
• NoDisplay: Freeze rendering for the main screen while maintaining rendering for subwindows, recording, and APIs. Useful for headless mode to save resources and improve FPS during image recording.

Gimbal

The Gimbal element allows you to freeze camera orientation for pitch, roll, and/or yaw. This setting is ignored unless ImageType is -1.

• Stabilization: Defaults to 0, meaning no gimbal (i.e., the camera orientation changes with the body orientation on all axes). A value of 1 means full stabilization. Any value between 0 and 1 acts as a weight for the fixed angles specified (in degrees, in the world frame) in the Pitch, Roll, and Yawelements, along with the orientation of the vehicle body. If any of the angles is omitted from the JSON or set to NaN, that angle is not stabilized (i.e., it moves with the vehicle body).

TimeOfDay

This setting controls the position of the Sun in the environment.

Enabled: Defaults to false. If true, the Sun’s position is computed using longitude, latitude, and altitude specified in OriginGeopoint for the date specified in StartDateTime.

StartDateTime: String format %Y-%m-%d %H:%M:%S. If empty, current date and time are used. Example: 2018-02-12 15:20:00.

StartDateTimeDst: Adjusts for daylight savings time if true.

UpdateIntervalSecs: Sets how frequently the Sun’s position is updated.

CelestialClockSpeed: Controls how fast the Sun moves in the sky relative to simulation time. Example: 100 means the Sun advances 100 seconds for every 1 second of simulation time.

Once we have all the configurations set up, we can start the GRID session through our terminal which is covered in the next section.