# TNT Topo - QGIS Project Files

## Overview
This repository contains QGIS project files for the TNT team's new Topographic map service. The project files define map layers, styling, and data sources for cartographic production.

## Test Project Files
These files are used for testing and development purposes:
- **data/earth.qgs** - Test file containing selected Natural Earth dataset layers
- **data/test.qgs** - MVP - Test project file

## 📚 Documentation

### Project Documentation
- **[Topo 2025 Guide](docs/Topo_2025.md)** - Project specifications
- **[QLR Scripts Guide](scripts/QLR_Scripts_README.md)** - QLR layer handling documentation

### 🛠️ Automation Tools

#### Layer Documentation Generator
Generates comprehensive documentation optimized for GitHub Wiki publishing:

```bash
# Generate documentation from a project file
python3 scripts/document_qgis_layers.py ./data/test.qgs \
  --output docs/Layer-Documentation.md

# Generate without legends (faster)
python3 scripts/document_qgis_layers.py ./data/test.qgs \
  --no-legends --output docs/Quick-Reference.md
```

## 🛠️ Utility Scripts

### Installing Dependencies
```bash
pip install -r requirements.txt
```

### Setup
1. **Set up Git hooks** (recommended):
   ```bash
   python3 scripts/install_hooks.py
   ```

2. **Open a project in QGIS**:
   - Launch QGIS
   - Open a project file from the `data/` directory (e.g., `data/test.qgs`)

### 🔧 Environment Setup
For database connections, set up environment variables:
```bash
export QGIS_DB_PASSWORD="your_database_password"
export QGIS_DB_USER="your_username"
```

## Available Scripts

The `/scripts` directory provides automation tools:

| Script | Purpose |
|--------|---------|
| **`clean_qgis_for_git.py`** | Removes credentials before Git commits |
| **`qgis_handling.py`** | Password restoration, datasource operations |
| **`install_hooks.py`** | Installs Git hooks for credential protection |
| **`download_data.py`** | Downloads Natural Earth test datasets |
| **`document_qgis_layers.py`** | Generates comprehensive layer documentation |
| **`add_layer.py`** | Add layers to QGIS projects |
| **`create_project_from_qlr.py`** | Create projects from QLR files |
| **`batch_process_qlr_with_qgis.py`** | Batch process QLR files |
| **`load_qlr_simple.py`** | Simple QLR loading utility |

## 💻 Usage Examples

### 🔐 Credential Management
#### Clean Projects Before Committing
```bash
# Clean all QGIS files in data directory (recommended before commits)
python3 scripts/clean_qgis_for_git.py -d ./data -v

# Clean specific project file
python3 scripts/clean_qgis_for_git.py -f ./data/test.qgs -v
```

#### Restore Credentials for Development
```bash
# Restore passwords from environment variables
python3 scripts/qgis_handling.py --reinsert-passwords -v

# Restore specific project
python3 scripts/qgis_handling.py --reinsert-passwords -f ./data/test.qgs -v
```

### 📥 Development Data Setup
#### Natural Earth Test Data
Download Natural Earth datasets for development and testing:

```bash
# Download all test datasets (countries, lakes, boundaries)
python3 scripts/download_data.py -v

# Download specific datasets only
python3 scripts/download_data.py -s countries lakes -v

# Force redownload and conversion to FlatGeobuf
python3 scripts/download_data.py --force -v
```

> **⚠️ Note**: Requires GDAL/OGR tools for FlatGeobuf conversion. Install with: `conda install gdal` or `apt-get install gdal-bin`

## 🏗️ Development Workflow

### 🔄 Recommended Development Process
1. **Pull latest changes**: `git pull origin main`
2. **Clean credentials**: `python3 scripts/clean_qgis_for_git.py -d ./data -v`
3. **Restore passwords**: `python3 scripts/qgis_handling.py --reinsert-passwords -v`
4. **Work in QGIS**: Make your changes
5. **Clean before commit**: Pre-commit hook automatically runs
6. **Commit and push**: `git add . && git commit -m "Description" && git push`

### Contributing
For contributing to this repository:
1. Ensure your QGIS project files are cleaned of credentials before committing
2. Install the Git hooks to automatically prevent committing files with credentials
3. Use environment variables for storing sensitive data

## Repository Structure
- **data/** - QGIS project files and layer definitions (QLR files)
- **docs/** - Documentation and guides
- **fonts/** - Custom fonts for map rendering
- **proj/** - Projection definitions
- **runtime/** - Server initialization scripts
- **scripts/** - Automation and utility scripts
- **styles/** - QML and SLD style files for map layers