README.md

---

license: apache-2.0
library_name: pytorch
tags:
- robotics
- point-cloud
- terrain-analysis
- autonomous-navigation
- 3d-perception
- deep-learning
- PointNet
---


# TerrainFreeSpaceNet

TerrainFreeSpaceNet is a deep learning model designed to predict **terrain free-space from 3D point cloud data**.  
It enables robots to estimate terrain traversability in uneven environments using raw point cloud observations.

This model is based on a **PointNet-style neural network** that processes unordered 3D points and outputs a normalized free-space score.

---

# Overview

Autonomous ground robots operating in outdoor environments often encounter:

- uneven terrain
- vegetation
- slopes and depressions
- irregular obstacles

Traditional geometric free-space detection methods may struggle in these environments.

TerrainFreeSpaceNet learns to **estimate terrain traversability directly from 3D point clouds**, making it suitable for:

- outdoor robotics
- off-road navigation
- agricultural robots
- exploration robots

---

## Model Architecture

The model uses a **PointNet-style architecture** consisting of:

1. Shared MLP layers implemented using Conv1D
2. Batch normalization and ReLU activation
3. Global max pooling
4. Fully connected regression layers
5. Sigmoid output for normalized free-space score

Input shape:

    [B, 3, N]


Where:

- `B` = batch size  
- `3` = (x,y,z) coordinates  
- `N` = number of sampled points  

Output:

    [B,1]


Free-space score in range:

- 0 → non-traversable
- 1 → highly traversable


---

## Input Format

The model expects **CSV point cloud input**.

Example:

    x,y,z

    0.12,0.31,0.02

    0.15,0.34,0.05

    0.18,0.29,0.04



---

## Example Inference

Example usage using the provided inference script.

```python

from inference import run_inference



score = run_inference("sample_input.csv", checkpoint="model.pt")



print("Free space score:", score)

```

Example output:

```

Free space score: 0.84

```

## Training

The model was trained using frame-level 3D point cloud samples.

Each frame contains:

```

frame_id,x,y,z,free_space

```
Where:

- `frame_id` identifies the point cloud frame

- `free_space` represents terrain traversability score

## Applications

TerrainFreeSpaceNet can be used for:

- terrain-aware robot navigation

- autonomous ground vehicles

- off-road robotics

- agricultural robots

- exploration robots

- rough terrain mobility analysis

## Limitations

- The model currently assumes XYZ coordinates only

- Performance depends on training dataset diversity

- Large terrain variations may require retraining

- Real-time deployment requires optimized inference

## Related Research

This model was developed as part of research on:

**Autonomous robot navigation in uneven terrain using 3D perception**.

It is designed to integrate with the **Agoraphilic-3D Navigation Framework**.

Repository

Full project code available here:

https://github.com/dinusharg/TerrainFreeSpaceNet



## Citation

If you use this model in research, please cite:

```bibtex

@article{10.1007/s12555-025-0624-2,

   author = {Gunathilaka, W. M. Dinusha and Kahandawa, Gayan and Ibrahim, M. Yousef and Hewawasam, H. S. and Nguyen, Linh},

   title = {Agoraphilic-3D Net: A Deep Learning Method for Attractive Force Estimation in Mapless Path Planning for Unstructured Terrain},

   journal = {International Journal of Control, Automation and Systems},

   volume = {23},

   number = {12},

   pages = {3790-3802},

   ISSN = {2005-4092},

   DOI = {10.1007/s12555-025-0624-2},

   url = {https://doi.org/10.1007/s12555-025-0624-2},

   year = {2025},

   type = {Journal Article}

}