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:

​

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:

​

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.

​

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 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.

​

Camera Noise Settings

"NoiseSettings": [
    {
      "Enabled": true,
      "ImageType": 0,
      "RandContrib": 0.687,
      "RandSpeed": 589423.8,
      "RandSize": 237.4,
      "RandDensity": 5.3,
      "HorzWaveContrib": 0.682,
      "HorzWaveStrength": 0.156,
      "HorzWaveVertSize": 3.42,
      "HorzWaveScreenSize": 0.79,
      "HorzNoiseLinesContrib": 0.731,
      "HorzNoiseLinesDensityY": 0.168,
      "HorzNoiseLinesDensityXY": 0.112,
      "HorzDistortionContrib": 0.91,
      "HorzDistortionStrength": 0.0374
    }
  ]

​

Random Noise

This effect introduces random noise blobs to the image. The appearance and behavior of this noise can be fine-tuned using the parameters below:

• RandContrib: Controls the blend ratio between the original pixel and the noise pixel. A value of 0 indicates no noise, while 1 means the pixel is entirely replaced by noise.
• RandSpeed: Dictates the fluctuation speed of the noise. A value of 1 results in no fluctuation. Higher values, such as 1E6, lead to maximum fluctuation.
• RandSize: Determines the coarseness of the noise. A value of 1 means each pixel receives unique noise. Larger values indicate that multiple pixels will share the same noise value, creating a coarser effect.
• RandDensity: Specifies the proportion of pixels affected by noise. A value of 1 means all pixels will have noise. Higher values exponentially decrease the number of noisy pixels.

​

Horizontal Bump Distortion

This effect simulates horizontal bumps, flickering, or ghosting artifacts. The characteristics of this distortion are controlled by:

• HorzWaveContrib: Sets the blend ratio between the original pixel and the noise pixel, where 0 means no noise and 1 means only noise.
• HorzWaveStrength: Adjusts the overall intensity of the distortion effect.
• HorzWaveVertSize: Defines the number of vertical pixels impacted by the effect.
• HorzWaveScreenSize: Determines the extent of the screen area affected by this distortion.

​

Horizontal Noise Lines

This effect introduces horizontal lines or regions of noise across the image. The following parameters control its appearance:

• HorzNoiseLinesContrib: Manages the blend ratio of noise pixels with image pixels. A value of 0 signifies no noise, while 1 indicates complete noise.
• HorzNoiseLinesDensityY: Specifies the number of pixels within a horizontal line that are affected by noise.
• HorzNoiseLinesDensityXY: Determines the quantity of noise-affected lines that appear on the screen.

​

Horizontal Line Distortion

This effect introduces fluctuations along horizontal lines in the image. Its behavior is governed by:

• HorzDistortionContrib: Controls the blend ratio between the original pixel and the noise pixel. A value of 0 results in no noise, and 1 means the pixel is entirely noise.
• HorzDistortionStrength: Adjusts the magnitude of the distortion.

​

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.

​

Sub-Windows

Sub-Windows are configurable display panels that show different camera views when activated with the numeric keys 1, 2, or 3. Each subwindow can be customized to display various image types from any available camera on your vehicles or external sources.

​

Configuration Parameters

• WindowID: Integer value (0-2) that identifies the subwindow position
• CameraName: String referencing any available camera on the vehicle or external camera
• ImageType: Integer that determines the visualization type according to the ImageType enum
• Visible: Boolean that controls whether the subwindow is displayed
• VehicleName: Optional string that specifies which vehicle’s camera to use when multiple vehicles are present (ignored if camera is external)
• External: Boolean that indicates if the camera is an external source (true) or vehicle-mounted (false)

​

Default Behavior

• If VehicleName contains errors or references a non-existent vehicle, the first vehicle’s camera will be used
• When using an external camera (External: true), the VehicleName parameter is ignored

​

Examples

​

Single Vehicle Configuration

This example shows three different views: driver perspective (scene), front bumper (depth), and rear view (surface normals):

"SubWindows": [
  {"WindowID": 1, "ImageType": 4, "CameraName": "2", "Visible": true},
  {"WindowID": 0, "ImageType": 3, "CameraName": "5", "Visible": true},
  {"WindowID": 2, "ImageType": 6, "CameraName": "0", "Visible": true}
]

​

Multi-Vehicle Configuration

This configuration displays different views from cameras on separate vehicles:

"SubWindows": [
  {"WindowID": 0, "CameraName": "1", "ImageType": 5, "VehicleName": "DeliveryBot", "Visible": true},
  {"WindowID": 2, "CameraName": "3", "ImageType": 2, "VehicleName": "Husky", "Visible": false},
  {"WindowID": 1, "CameraName": "2", "ImageType": 7, "VehicleName": "Scout", "Visible": true}
]

​

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.