Metadata-Version: 2.4
Name: standardgrid
Version: 1.0.0
Summary: Python library for generating official spatial reference grids aligned with recognised standards.
Author: Pedro Monteiro
License: MIT
Project-URL: Homepage, https://github.com/pmontei/standardgrid
Project-URL: Repository, https://github.com/pmontei/standardgrid
Project-URL: Issues, https://github.com/pmontei/standardgrid/issues
Keywords: gis,grid,spatial,marine,habitat,csquares,inspire,emodnet
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: openpyxl>=3.1
Dynamic: license-file

# StandardGrid

**StandardGrid** is a lightweight Python library for generating **standards-compliant spatial reference grids** aligned with recognised reference systems such as **C-Squares** and **INSPIRE**.

The library was originally developed within the **EMODnet Seabed Habitats** project to support the harmonisation and automation of composite habitat map production carried out under **Work Package 3 (WP3)**. Its primary objective is to provide a reproducible and standardised way of generating reference grids for large-scale spatial analyses and map compilation.

Although initially developed for EMODnet Seabed Habitats, StandardGrid is intended as a general-purpose library for any GIS application requiring official and reproducible spatial reference grids.

---

## Why StandardGrid?

Combining spatial datasets from different sources is often challenging because they are produced using different grid origins, spatial resolutions or processing workflows.

StandardGrid addresses this problem by generating centroid grids that are precisely aligned with recognised spatial reference standards, ensuring that different datasets can be integrated consistently and reproducibly.

Typical applications include:

* Essential Fish Habitats (EFH)
* Vulnerable Marine Ecosystems (VME)
* Essential Ocean Variables (EOV)
* Habitat suitability modelling
* Marine spatial planning
* Environmental assessments
* Large-scale composite habitat mapping
* Any workflow requiring standards-aligned reference grids

---

## Features

* Official C-Squares support
* Official INSPIRE support
* Automatic alignment to official reference grids
* Validation of supported resolutions
* Standards-compliant centroid generation
* Pandas DataFrame output
* CSV export
* Excel export
* Simple and lightweight Python API

---

## Installation

Install directly from PyPI:

```bash
pip install standardgrid
```

or install from the GitHub repository:

```bash
git clone https://github.com/pmontei/standardgrid.git

cd standardgrid

pip install .
```

---

## Quick Start

```python
from standardgrid import Grid

grid = Grid(
    standard="csquares",
    resolution=0.01,
)

grid.generate(
    (-10.1, 36.6, -7.3, 41.9)
)

print(grid.points.head())

grid.to_csv("grid.csv")
```

---

## Supported Standards

StandardGrid currently supports the following official spatial reference systems.

| Standard     | CRS       | Units   |
| ------------ | --------- | ------- |
| C-Squares    | EPSG:4326 | Degrees |
| INSPIRE Grid | EPSG:3035 | Metres  |

Additional standards may be incorporated in future releases.

---

## Supported Resolutions

Each supported standard defines a fixed set of official grid resolutions.

StandardGrid validates the requested resolution automatically to ensure compliance with the selected standard.

| Standard  | Resolution | Description            |
| --------- | ---------: | ---------------------- |
| C-Squares |        10° | Global reference grid  |
| C-Squares |         5° |                        |
| C-Squares |         1° |                        |
| C-Squares |       0.5° |                        |
| C-Squares |       0.1° |                        |
| C-Squares |      0.05° | ICES statistical grid  |
| C-Squares |      0.01° | Common habitat mapping |
| INSPIRE   |   100000 m | 100 km                 |
| INSPIRE   |    10000 m | 10 km                  |
| INSPIRE   |     1000 m | 1 km                   |
| INSPIRE   |      100 m | 100 m                  |
| INSPIRE   |       10 m | 10 m                   |
| INSPIRE   |        1 m | 1 m                    |

Attempting to use an unsupported resolution raises a `ValueError`.

---

## Discover Available Standards

The supported standards and their properties can be queried directly from the API.

```python
from standardgrid import available_standards, get_standard

for code in available_standards():

    standard = get_standard(code)

    print(standard.name)
    print(standard.crs)
    print(standard.units)
    print(standard.resolutions)
```

Example output:

```text
C-Squares
EPSG:4326
degrees
(10.0, 5.0, 1.0, 0.5, 0.1, 0.05, 0.01, 0.005, 0.001, 0.0005, 0.0001, 0.00005, 0.00001)

INSPIRE
EPSG:3035
metres
(100000.0, 10000.0, 1000.0, 100.0, 10.0, 1.0)
```

---

## Project Background

StandardGrid was originally developed within the **EMODnet Seabed Habitats** project to support the harmonisation and automation of composite habitat mapping workflows developed under **Work Package 3 (WP3)**.

The library was initially designed to facilitate the production of harmonised pan-European spatial products, including:

* Essential Fish Habitats (EFH)
* Vulnerable Marine Ecosystems (VME)
* Essential Ocean Variables (EOV)

By ensuring that all datasets share exactly the same spatial reference grid, StandardGrid simplifies rasterisation, spatial overlay, data aggregation and reproducible GIS workflows.

Although originally developed for marine habitat mapping, the library is applicable to any GIS workflow requiring official standards-aligned reference grids.

---

## Citation

If StandardGrid contributes to your work, please cite the project and acknowledge the **EMODnet Seabed Habitats** initiative where appropriate.

---

## License

This project is released under the **MIT License**.

---

**Developed by**

Pedro Monteiro
CCMAR – Centre of Marine Sciences
University of Algarve

**Project**

EMODnet Seabed Habitats
