Metadata-Version: 2.4
Name: cartomize
Version: 0.9.0a1
Summary: Cartographic layouts, raster analysis and automated geospatial workflows
Author: ONDON NKOUA Cédrick Belmich
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/cedrick14/cartomize-python
Project-URL: Repository, https://github.com/cedrick14/cartomize-python
Project-URL: Issues, https://github.com/cedrick14/cartomize-python/issues
Project-URL: Documentation, https://github.com/cedrick14/cartomize-python/blob/main/docs/DESKTOP.md
Keywords: cartography,gis,geopandas,raster,map-layout
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: geopandas<2,>=1.0
Requires-Dist: matplotlib<4,>=3.8
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pyproj<4,>=3.6
Requires-Dist: rasterio<2,>=1.4
Requires-Dist: scipy<2,>=1.11
Requires-Dist: scikit-learn<2,>=1.5
Provides-Extra: gui
Requires-Dist: PySide6-Essentials<6.10,>=6.9.3; extra == "gui"
Requires-Dist: pypdfium2<6,>=4.30; extra == "gui"
Provides-Extra: notebook
Requires-Dist: PySide6-Essentials<6.10,>=6.9.3; extra == "notebook"
Requires-Dist: pypdfium2<6,>=4.30; extra == "notebook"
Requires-Dist: ipykernel<8,>=6.29; extra == "notebook"
Requires-Dist: jupyter-client<9,>=8.6; extra == "notebook"
Requires-Dist: typing_extensions<5,>=4.13; extra == "notebook"
Provides-Extra: distributed
Requires-Dist: dask[distributed]<2027,>=2024.8; extra == "distributed"
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x[ctk]<15,>=14; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: twine<8,>=6; extra == "dev"
Dynamic: license-file

# Cartomize

**Cartographic assistant for Python — Assistant cartographique pour Python**

Cartomize combines satellite image preparation, raster and vector processing,
and cartographic layouts in a Python library with an optional desktop interface.
It is developed by **ONDON NKOUA Cédrick Belmich**, founder of Cartomize.

The standalone library and its desktop interface work **without QGIS or ArcGIS Pro**.
Optional native project bridges require the corresponding installed GIS software.

## Installation

Python 3.11 or newer is required. Version **0.9.0a1 is an alpha release**.
Linux and Windows have been tested with Python 3.11 and 3.12.

```bash
python -m pip install "cartomize==0.9.0a1"
```

The desktop interface requires Python 3.11–3.13 and selects the tested Qt 6.9 series automatically. For the interface and optional Dask execution:

```bash
python -m pip install "cartomize[gui,distributed]==0.9.0a1"
python -m cartomize gui
```

Or open the interface from Python:

```python
import cartomize as cm
cm.launch()
```

Importing the library does not open a window automatically.

### Jupyter notebooks on a local computer

Install the notebook extra in a Python 3.11–3.13 kernel:

```python
%pip install "cartomize[notebook]==0.9.0a1"
```

Restart the kernel after upgrading, then run:

```python
import cartomize as cm
window = cm.launch()
```

Cartomize enables the Qt event loop automatically so the cell returns while
its desktop window remains responsive. The window opens on the computer
running the kernel; a headless or remote notebook cannot display it in the
browser. The processing API works without a desktop.

Version 0.9.0a1 preserves selected spectral bands throughout automation, connects classification validation settings, and checks map quality before automated export.

See the [GIS workflow audit](https://github.com/cedrick14/cartomize-python/blob/main/docs/SIG_WORKFLOWS.md) for processing order, verified connections and remaining limitations.

The startup improvements introduced in 0.8.1a2 initialize Python's XML parser before geospatial DLLs are
loaded, addressing Windows Conda startup conflicts. It also adds the
`notebook` extra with a compatible `typing_extensions` requirement.

## Integrated results workspace

The desktop now uses two resizable panels: processing controls on the left, results on the right. Raster and vector layers, map PDFs/SVGs, images, tables, reports and plots open in embedded tabs. Raster zoom reads the visible source window at the requested resolution; display settings never rewrite scientific values.

Compare results side by side with linked geographic extents and an optional common colour scale. Inspect band values, legends, coordinates and metadata. CSV and attribute tables are paged; plots use the displayed page. Existing results remain navigable while processing runs. See the [workspace guide](https://github.com/cedrick14/cartomize-python/blob/main/docs/RESULTS_WORKSPACE.md) for controls and limits.

## Satellite image preparation

Select spectral bands and a polygonal area of interest, then choose mosaicking,
multiband assembly, clipping, RGB composition and separate band exports.
Landsat Collection 2 Level 2 and Sentinel-2 Level 2A products are recognized
from their original filenames and metadata. Other inputs use explicit band
and scene mappings.

```python
import cartomize as cm

result = cm.process_imagery(
    ["scene_A", "scene_B"],
    "outputs/preparation",  # a new directory
    aoi="study_area.shp",
    mosaic=True,
    multiband=True,
    separate_bands=True,
    composition=("nir", "red", "green"),
)
print(result.manifest)
```

Calibration and quality masking precede resampling. Scientific multiband values
remain separate from stretched display values. Turning off mosaicking processes
each scene independently. For an existing multiband file:

```python
band_files = cm.split_bands("multiband.tif", "outputs/separate_bands")
```

## Capabilities

- Multiscene preparation, NoData masks, RGB composites and spectral indices.
- Raster algebra, focal statistics, multiraster reductions and terrain derivatives.
- Vector overlay, spatial joins, buffers, clipping and geometry repair.
- Supervised and unsupervised classification with explicit training inputs where required.
- Cartographic layouts, legends, scale bars, labels, 24 templates and PDF/PNG/SVG exports.
- Optional desktop workflows, saved sessions and portable projects.
- Dask execution for supported raster operators; optional CUDA for algebra, indices and reductions.

## Utilisation en français

Cartomize permet de préparer les images satellitaires, traiter les couches et
produire les cartes dans Python ou dans une fenêtre dédiée. Dans
**Prétraitement multispectral**, charger les bandes, vérifier les scènes, importer
la délimitation, cocher les opérations et choisir les bandes des canaux rouge,
vert et bleu. Les GeoTIFF scientifiques, les compositions colorées et les bandes
extraites sont enregistrés séparément.

L’interface conserve l’icône Cartomize en couleur et utilise des intitulés
techniques. Les indices et la mise en page restent accessibles à partir des
résultats de préparation.

## Documentation and support

- [Source code](https://github.com/cedrick14/cartomize-python)
- [Desktop guide](https://github.com/cedrick14/cartomize-python/blob/main/docs/DESKTOP.md)
- [Image preparation guide](https://github.com/cedrick14/cartomize-python/blob/main/docs/IMAGERY_SELECTION.md)
- [Execution engines](https://github.com/cedrick14/cartomize-python/blob/main/docs/EXECUTION.md)
- [Issue tracker](https://github.com/cedrick14/cartomize-python/issues)

## Validation and scope

The 0.8.1 code passed 315 tests in each Linux/Windows and Python 3.11/3.12
configuration, including 38 Qt cases. QGIS native integration was tested
separately in a real QGIS runtime. CUDA hardware execution and ArcGIS Pro
integration still require validation on suitable licensed/equipped machines.
Tests use synthetic data; no universal performance gain is claimed.

The library uses GeoPandas, Rasterio, NumPy, SciPy, Matplotlib and scikit-learn.
PySide6, Dask and CuPy are optional dependencies. This alpha does not reproduce
every native GIS rendering effect and is not endorsed by QGIS, Esri or GeoPandas.

## License

Source code: **GNU GPL v3 only**. The original layout templates are **CC BY 4.0**,
attributed to Cartomize / ONDON NKOUA Cédrick Belmich. License notices are included
in the distribution.
