Configuration Settings

This section provides a comprehensive guide to configuring the GRID Enterprise. Understanding and correctly setting up these configurations is essential using the platform. Once you have succesfully 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:

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

Note

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. For example, "Default," "Matrice300RTK," or "eVTOL" for drones; "Default," "MCR," "Offroad," "SUV," "Rover," "Forklift," or "Tractor" for cars.

    • X, Y, Z: Defines the starting position of the vehicle in the simulation environment.

Multi-Agent simulation

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

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

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

Camera Settings

  • CameraDefaults: Specify camera configuration, such as resolution, 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). This setting is part of the camera's configuration.

    • 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, which are critical for geospatial simulations.

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

  • Latitude/Longitude/Altitude: These values determine the initial placement of the robot in a geospatial context, providing accurate real-world positioning.

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 Yaw elements, 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.