===========================================================
README - DEM-AIA Planner in MATLAB
===========================================================

Authors: Toscano-Moreno, M., Mandow, A., Martínez, M.A., García-Cerezo, A.
Reference: DEM-AIA: Asymmetric inclination-aware trajectory planner for 
           off-road vehicles with digital elevation models.
           Engineering Applications of Artificial Intelligence, 121, 105976, 2023.
           DOI: https://www.doi.org/10.1016/j.engappai.2023.105976
           GREEN OPEN ACCESS: https://hdl.handle.net/10630/26534
License: Open Access

-----------------------------------------------------------
1. GENERAL DESCRIPTION
-----------------------------------------------------------
This package provides the DEM-AIA (Digital Elevation Map – Any-Angle 
Inclination-Aware) trajectory planner for unmanned ground vehicles (UGVs).

The planner computes feasible and efficient trajectories over digital 
elevation models (DEMs), explicitly considering:

- Terrain slopes (pitch and roll).
- Vehicle dynamic and geometric constraints (speed, center of gravity, 
  length, width, slope tolerance).
- Any-angle variant of the A* algorithm for more realistic and shorter paths.
- Optional heuristic search and node re-expansion.

The distribution includes both synthetic and real DEMs, MATLAB source code, 
precompiled MEX binaries, and a test script.

-----------------------------------------------------------
2. PACKAGE CONTENTS
-----------------------------------------------------------

Main files:

- test-DEMAIA.m
  Main test script. Loads DEMs, defines UGV constraints, executes the planner, 
  and visualizes results (3D and 2D plots).

- DeMAIA.mexw64
  Precompiled MEX implementation of the DEM-AIA planner.

- analysisWaypoints.mexw64
  Post-processing tool for planned trajectories. Provides metrics such as 
  maximum slope, tilt, path length, navigation time, and turning effort.

- computeLUT.mexw64
  Builds the Look-Up Table (LUT) of inclination-aware velocity constraints 
  (pitch/roll).

- MEXfiles_R2021b.zip
  Compressed archive with the MEX binaries for MATLAB R2021b (Windows x64).

- realworldDEM.mat
  Real-world Digital Elevation Model.

- syntheticDEM_01.mat, syntheticDEM_02.mat, syntheticDEM_03.mat
  Synthetic Digital Elevation Models for controlled experiments.

- .gitattributes
  Git configuration file (not required for execution).

-----------------------------------------------------------
3. DIGITAL ELEVATION MODELS (DEMs)
-----------------------------------------------------------

Format: MATLAB .mat files containing:
- DEM.Z : 2D matrix of elevation values (altitude in meters).

Available DEMs:
- Synthetic: syntheticDEM_01, syntheticDEM_02, syntheticDEM_03.
  Useful for benchmarking and controlled experiments.

- Real: realworldDEM.
  A realistic terrain dataset with larger scale and more complex slopes.

-----------------------------------------------------------
4. SOFTWARE REQUIREMENTS
-----------------------------------------------------------

- MATLAB R2021b (recommended). 
- Operating System: Windows 64-bit (required for provided .mexw64 binaries).
- Optional: MATLAB Mapping Toolbox (enables advanced terrain visualization 
  with demcmap).

-----------------------------------------------------------
5. EXECUTION
-----------------------------------------------------------

1. Open MATLAB.
2. Place all files in a single working directory.
3. Add the directory to the MATLAB path.
4. Run the main script:

   >> test-DEMAIA

The script will display:
- 3D view of the DEM with outbound and return trajectories.
- 2D projection of the DEM with trajectories.
- UGV pitch/roll stability region.

The MATLAB console will print path planning metrics such as explored nodes, 
path length, travel time, maximum slope, tilt, and computation time.

-----------------------------------------------------------
6. CONFIGURATION PARAMETERS
-----------------------------------------------------------

Within test-DEMAIA.m:

- DEMtype = true / false
  DEM selection: true = synthetic DEM, false = real-world DEM.

- constraints_UGV_DEMAIA
  UGV parameters: [nominal speed, slope sensitivity factors, center of gravity, 
  length, width, slope tolerance].

- features_DEMAIA
  Planner features: [any-angle, heuristic enabled, heuristic function, reexpansion].

- c0, cn
  Start and goal coordinates. Must be within the DEM size.

-----------------------------------------------------------
7. METADATA
-----------------------------------------------------------

- Application domain: Off-road robotics, terrain-aware trajectory planning.
- Data type: Digital Elevation Models (DEMs).
- Format: MATLAB .mat.
- Spatial resolution: depends on the selected DEM.
- Units: meters (altitude and coordinates).
- Restrictions: Distributed MEX files only run on MATLAB R2021b (Windows x64). 
  Recompilation is required for other versions or platforms.

-----------------------------------------------------------
8. LICENSE
-----------------------------------------------------------

Open Access dataset and software.

Reference to cite:
Toscano-Moreno, M., Mandow, A., Martínez, M.A., García-Cerezo, A. 
DEM-AIA: Asymmetric inclination-aware trajectory planner for off-road 
vehicles with digital elevation models. 
Engineering Applications of Artificial Intelligence, 121, 105976, 2023. 
DOI: https://www.doi.org/10.1016/j.engappai.2023.105976

===========================================================