Conventions#
This page gives the units, the frames, the signs and the notation that all model pages use. It also lists the models.
The Models#
| Model | Page | Main Source Files |
|---|---|---|
| Maxxum 150 dynamics | Maxxum 150 Dynamics | AcresVehicleModel, AcresSimModel |
| Polaris Ranger dynamics | Polaris Ranger Dynamics | AcresUtvModel |
| Drive-by-wire and ULC | Drive-by-Wire and ULC | AcresUtvModel, AcresCommandTiming.h |
| Tyre and soil | Tyre and Soil | AcresSoilModel, AcresVehicleModel |
| Energy and fuel | Energy and Fuel | AcresPowerModel |
| Implement mechanics | Implement Mechanics | AcresImplementModel, AcresImplementCoupling |
| Each implement | Implement Catalog | AcresImplementModel, implements/*.json |
| Crops and ground classes | Crops and Ground Classes | AcresFarmModel, AcresSurfaceMap |
| Soil water | Soil Water | AcresFarmModel, AcresFarmRuntime |
| Weather | Weather | AcresEnvironmentModel |
| The scene and its frames | The ACRE Scene | AcresGeoUtm.h, the map products |
| Farm traffic and workers | Farm Traffic and Workers | AcresNpc |
| Optimizer | Optimizer | AcresOptimizer |
| Camera | Camera | AcresCameraModel |
| LiDAR | LiDAR | AcresLidarModel, AcresLidarPhysics.h |
| INS and GNSS | INS and GNSS | AcresGnssModel |
| Wheel and CAN signals | Wheel and CAN Signals | AcresRlBridge |
| Time stepping | Time Stepping and Determinism | AcresVehicle, AcresCommandTiming.h |
All source files are in Acres/Source/Acres.
Structure of a Model Page#
Each model page has the same sections in the same sequence.
- Scope and Assumptions. What the model computes and what it ignores.
- Symbols. Each symbol with its quantity and its unit.
- The parts of the model. The equations, with the source function of each part.
- Parameters. Each configuration key with its type, unit and default.
- Code Map. The file and the function of each item.
- Limitations.
- References. The publications of the model.
The default of a parameter is the value in the shipped configuration file.
Units#
The models use SI units. A key or a variable states its unit in its name.
| Quantity | Unit in the Models | Suffix in JSON Keys | Suffix in C++ Names |
|---|---|---|---|
| Length | m | _m |
M |
| Area | m² | _m2 |
M2 |
| Mass | kg | _kg |
Kg |
| Time | s | _s, _h |
S |
| Force | N | _n |
N |
| Torque | N·m | _nm |
Nm |
| Pressure | Pa | _pa, _kpa, _bar |
Pa |
| Speed | m/s | _mps |
Mps |
| Acceleration | m/s² | _mps2 |
Mps2 |
| Angle | rad | _deg |
Rad, Deg |
| Engine speed | rad/s | _rpm |
Rpm, Radps |
| Power | W | _kw, _hp |
W, KW |
| Temperature | °C | _c |
C |
| Volume | L | _l |
L |
| Share | 1 | _pct |
Pct |
A configuration key uses the unit of the datasheet of the machine when that is more usual, for example degrees and kilowatts. The suffix of the key states the unit. The model changes the value to SI when it reads the file.
Unreal measures lengths in centimetres. The code changes the unit only where a position enters or leaves the engine.
Frames#
| Frame | Axes | Origin | Use |
|---|---|---|---|
| World | x east, y north, z up (ENU) | The centre of the tile | Poses in the episode log, ACRES Core, the map products. |
| Unreal world | X east, Y south, Z up, in cm | The centre of the tile | Inside the game only. |
| Survey grid | u east, v south, in cells of 1.524 m | The north-west corner of the tile | Fields, places and spawn poses. |
| UTM zone 16N | easting, northing | The UTM origin | The odometry and the fix of the vehicle on ROS 2. |
| Body | x forward, y left, z up (FLU) | base_footprint |
Velocities, forces and sensor mounts. |
base_footprint is the point on the ground below the centre of the rear axle.
Inside the game, the body frame of Unreal has Y to the right. The outputs of the simulator use FLU.
The ACRE Scene gives the conversions between the frames with their constants.
Signs#
| Quantity | Positive Direction |
|---|---|
| Steering angle and curvature | To the left. |
| Yaw and yaw rate | Counter-clockwise when you look from above. |
| Longitudinal slip | The wheel turns faster than it moves. |
| Longitudinal force on the chassis | Forward. |
| Lateral force in the body frame | To the left. |
| Sinkage and rut depth | Down into the soil. |
| Draft of an implement | Against the direction of travel. |
A model page states a different sign where the code uses one.
Notation#
| Notation | Meaning |
|---|---|
| \( x_k \) | The value of \( x \) at physics step \( k \). |
| \( \Delta t \) | The physics step, 1/120 s. |
| \( \dot{x} \) | The time derivative of \( x \). |
| \( \operatorname{clamp}(x, a, b) \) | The value \( x \) limited to the range from \( a \) to \( b \). |
| \( \operatorname{sgn}(x) \) | The sign of \( x \). |
| \( g \) | The standard acceleration of gravity, 9.80665 m/s² (StandardGravityMps2). |
Calibration Status#
Each model page states which parameters come from measurements and which come from publications. Limitations gives the summary.