qgis-ns-pe 0.1.3
A CLI tool for processing LiDAR data from Nova Scotia and PEI using QGIS
Requires Python: >=3.8

# QGIS Nova Scotia & PEI LiDAR Processing Tool

A command-line tool for processing LiDAR data from Nova Scotia and Prince Edward Island using QGIS. This tool allows you to:

- Geocode addresses in Nova Scotia and PEI
- Download and process LiDAR point cloud data
- Extract building footprints from LiDAR data
- Generate satellite imagery for the location
- Visualize 3D point clouds

## Features

- Address geocoding using OpenStreetMap Nominatim API
- Coordinate transformation between different CRS (WGS84, NAD83(CSRS), MTM zone 5)
- LiDAR point cloud processing using laspy
- Building point extraction
- 3D visualization capabilities
- Satellite imagery retrieval from Mapbox

## Prerequisites

- Python 3.8 or higher
- QGIS 3.22.0 or higher
- Conda (required for QGIS installation)

## Installation

The installation process has three steps: setting up QGIS, installing dependencies, and installing this package.

### 1. Install QGIS using Conda

First, create a new conda environment with QGIS installed:

```bash
# Create a new environment with QGIS and Python 3.8
conda create -n qgis-env -c conda-forge qgis python=3.8

# Activate the environment
conda activate qgis-env
```

### 2. Install Dependencies

Install required dependencies using conda:

```bash
conda install -c conda-forge pyproj numpy matplotlib
conda install -c conda-forge laspy lazrs
```

### 3. Install qgis-ns-pe

After activating the conda environment and installing dependencies, install this package:

```bash
# For users: install from PyPI (not yet available)
# pip install qgis-ns-pe

# For developers: install in editable mode from source
git clone https://github.com/amadgakkhar/qgis-ns-pe.git
cd qgis-ns-pe
pip install -e .
```

### Package Structure

The package should have the following structure:

```
qgis-ns-pe/
├── qgis_ns_pe/
│   ├── __init__.py
│   └── cli.py
├── setup.py
└── README.md
```

### Verification

To verify the installation:

```bash
# Make sure you're in the conda environment
conda activate qgis-env

# Try running the tool with --help
qgis-ns-pe --help
```

## Usage

The tool can be used from the command line with the following syntax:

```bash
qgis-ns-pe --address "Your Address" --index_path "/path/to/lidar_index.gpkg" [--show_3d]
```

Example:
```bash
qgis-ns-pe --address "8 Alderwood Dr, Halifax, NS B3N 1S7" --index_path "/path/to/Index_LiDARtiles_tuileslidar.gpkg" --show_3d
```

### Arguments

- `--address`: The address to process (required)
- `--index_path`: Path to the LiDAR index GPKG file (required)
- `--show_3d`: Optional flag to show 3D visualizations of the point clouds

### Output

The tool creates two directories:
- `lidar_tiles/`: Contains downloaded LiDAR tiles
- `output/`: Contains processed files:
  - `sat.png`: Satellite image of the location
  - `lidar_cropped.laz`: Cropped LiDAR point cloud
  - `buildings.laz`: Extracted building points

## Troubleshooting

Common issues and solutions:

1. **QGIS not found**: Make sure you've activated the conda environment with `conda activate qgis-env`
2. **Import errors**: Ensure you're running the tool from the conda environment where QGIS is installed
3. **Missing dependencies**: If you encounter any missing dependency errors, try installing them with conda first:
   ```bash
   conda install -c conda-forge <package-name>
   ```

## Data Sources

- LiDAR data: Nova Scotia and PEI government open data portals
- Geocoding: OpenStreetMap Nominatim API
- Satellite imagery: Mapbox Static Images API

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Authors

- Amad Gakkhar - Initial work

## Acknowledgments

- QGIS Development Team
- laspy contributors
- OpenStreetMap contributors
- Mapbox