Skip to content

Quickstart#

Drive a Polaris from Python, take one LiDAR scan, and then run a full mission. Each step takes less than a minute.

Before you start

  • Do the Python only path of the install.
  • Run each command in the repository root, in the Python environment of the builds.

Drive a Polaris#

acres_core is the Python module of ACRES Core. A Batch holds one or more Polaris worlds on the ACRE map.

  1. Write this script into the file first_core.py.

    first_core.py
    import numpy as np
import acres_core as ac

b = ac.Batch(".")                                                # the map and the configuration of this repository
b.reset(None, np.array([[-38.71, -140.513, np.pi / 2, 0.0]]))   # x, y, yaw, speed: the ICSC garage, heading north
for _ in range(50):                                               # 50 calls of 0.1 s: 5 s
    state = b.step_curvature_speed(np.array([0.0]), np.array([3.0]))
print({name: round(float(value), 3) for name, value in zip(ac.STATE_COLUMNS[:4], state[0])})
print("speed", round(float(state[0, ac.STATE_COLUMNS.index("speed")]), 2), "m/s")

  2. Run the script with the build folder on the module path.

    PYTHONPATH=Core/Build python first_core.py

    Expected result

    The Polaris moved approximately 9 m to the north in 5 s.

    {'time_s': 5.0, 'x': -38.47, 'y': -131.671, 'z': 0.363}
speed 3.33 m/s

The command is a path curvature (0 is straight) and a speed of 3 m/s. The drive-by-wire and the speed controller of the Polaris follow the command, as on the real vehicle. Each call of step_curvature_speed advances the simulation by 0.1 s, which is 12 physics steps at 120 Hz.

Take a LiDAR Scan#

  1. Write this script into the file first_scan.py.

    first_scan.py
    import numpy as np
import acres_core as ac

b = ac.Batch(".")
b.reset(None, np.array([[-38.71, -140.513, np.pi / 2, 0.0]]))
ranges, material = b.lidar(pattern="helios")                     # one scan of the Polaris LiDAR
hits = np.isfinite(ranges[0])                                    # NaN is a beam with no return
print("beams", ranges.shape[1], "returns", int(hits.sum()))
print("median range", round(float(np.nanmedian(ranges[0])), 1), "m")

  2. Run the script.

    PYTHONPATH=Core/Build python first_scan.py

    Expected result

    beams 57600 returns 43752
median range 3.8 m

The pattern helios has 1800 columns and 32 rings, as the RoboSense Helios of the Polaris. The second array gives the material of each return, for example terrain, plants or vehicle_box (ac.LIDAR_MATERIALS).

Run a Mission#

acres_simulator runs missions on the run-time library: the route, the planner, the shield and the controllers of the vehicle program. A mission named single-F56 drives from the home pose H to field F56, scouts the field and comes back to H.

  1. Write this script into the file first_mission.py.

    first_mission.py
    import acres_simulator as acres

world = acres.Core(num_envs=1, threads=4)                       # one vehicle slot, four threads
fleet = acres.Fleet(world, grip="unknown", shield_scan="planar")
fleet.load(missions=["single-F56"], condition="dry")            # scout field F56 and come back to H
fleet.run()                                                     # drive until the mission ends

score = fleet.scores()[0]
print(score["mission"], "success" if score["success"] else score["failure"])
print("time", round(score["time_s"], 1), "s   distance", round(score["distance_m"]), "m")
print("fuel", round(score["fuel_j"] / 1e6, 2), "MJ")

  2. Run the script.

    python first_mission.py

    Expected result

    The mission of 367 s of simulation time runs in approximately 8 s.

    single-F56 success
time 367.2 s   distance 1022 m
fuel 6.57 MJ
Argument Value in the Script Meaning
num_envs 1 The number of vehicle slots. A fleet drives its missions in parallel on these slots.
grip "unknown" The grip level of the speed envelope. "unknown" is the most careful level.
shield_scan "planar" The scan of the safety shield. "planar" is fast: this mission runs in approximately 8 s. "sweep" simulates the full LiDAR sweep: approximately 2 minutes. The default "config" uses corridor.scan_source of control_v1.json, which is "sweep".
condition "dry" The condition set of the cost tables of the planner: "dry", "wet" or "shift".

Note

The first plan of a condition set drives the cost tables of the map. This takes approximately 2 minutes. The cache then has the tables and the next plans start immediately.

Next Steps#