# Automatic Crater Detector 1.0  

`Automatic Crater Detector 1.0` is a Python-based module designed to perform inferences on images using a Faster R-CNN model for automatic crater detection.  

## Authors  

This code was developed by L. Martinez and Frédéric Schmidt and François Andrieu and collaborators (contacts: leonard.martinez@universite-paris-saclay.fr, francois.andrieu@universite-paris-saclay.fr) 

Date: January 15, 2025  

## Project Structure   

```bash
Craterdetector/
│── checkpoint/                      # Contains model weights for detection and  
│── data/                            # Contains input images
│── envs/                            # Contains environment setup files
│── outputs/                         # Stores inference results
│── inferences.py                    # Main script
│── model.py                         # Model definition file (not to be used directly)
│── parameters_for_inferences.yml    # YAML file containing the main parameters
```

## Installation  

Copy the project localy using git clone:

```bash
git clone git@gitlab.dsi.universite-paris-saclay.fr:path_to_project.git 
```
or 
```bash
git clone git@github.com:path_to_project.git 
```

then change directory into the repository on you computer, create a virtual environment and activate it:

using pip
```bash
cd envs/
python3 -m venv craterdetector
source craterdetector/bin/activate
pip install -r requirements.txt
```

or using Conda:  

```bash
cd envs/
conda env create --name inferences --file requirements.yml
conda activate inferences
```

**Note:**  
This project was developed using the following versions of Python packages. Compatibility with other versions has not been tested and is not guaranteed:  

```txt
python==3.9
rasterio==1.3.10
pandas==2.0.3
shapely==1.8.4
pyyaml==6.0
scipy==1.11.1
numpy==1.25.2
pillow==11.0.0
torch==2.5.1
torchaudio==2.5.0
torchvision==0.20.1
tqdm==4.66.5
```

## Configuration  

The `parameters_for_inferences.yml` file contains all the necessary parameters for running the crater detector, including:  

- Paths to the required files  
- Model parameters  

Example configuration:  

```yaml
input_data: "data/"
output_dir: "outputs/"
thresh_confidence: 0.5
```

## Usage  

The main script for running inference is `inferences.py`. It loads a pretrained Faster R-CNN model and performs inference on all the images located in the directory  `data_directory` mentioned in the yaml parameters file. The default data directory is `data/` and the default output directory is `outputs/`. Supported input images formats include `.png`, `.jpg`, and `.tif`. The default device the detector runs on is the cpu, but it is possible to run it on a GPU (e.g. device : `cuda:0`).  

### Running the script  

```bash
python inferences.py
```

## Results  

Inference results are saved in the `outputs/` directory.  

## Contributions  

Contributions are welcome! Please cite:  

L. Martinez et al. (2025), *Robust Automatic Crater Detection at All Latitudes on Mars with Deep Learning*, Planetary and Space Science.  

## License  

This project is licensed under CC-BY-SA.