Metadata-Version: 2.5
Name: taco-eo
Version: 0.11.0
Summary: Python bindings to libtaco, the reference library for the TACO format.
Project-URL: Homepage, https://asterisk.coop/taco
Project-URL: Specification, https://asterisk.coop/taco/spec
Project-URL: Repository, https://github.com/asterisk-labs/taco
Project-URL: Issues, https://github.com/asterisk-labs/taco/issues
Author-email: Cesar Aybar <cesar@asterisk.coop>
License-Expression: MIT
License-File: LICENSE
Keywords: cloud-optimized,cozip,earth-observation,geospatial,machine-learning,parquet,taco
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cffi>=1.17
Requires-Dist: cozip>=2026.9.4
Requires-Dist: duckdb>=1.5.5
Requires-Dist: numpy>=1.24
Requires-Dist: pyarrow>=14
Requires-Dist: pydantic>=2.8
Requires-Dist: pyproj>=3.6
Requires-Dist: shapely>=2
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: geoenrich
Requires-Dist: earthengine-api>=1; extra == 'geoenrich'
Provides-Extra: rumi
Requires-Dist: rumi-eo[write]>=0.19; extra == 'rumi'
Provides-Extra: test
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Provides-Extra: test-eo
Requires-Dist: rumi-eo[write]>=0.19; extra == 'test-eo'
Description-Content-Type: text/markdown

# taco

Read and write TACO datasets in Python.

```bash
pip install taco-eo
python examples/minimal.py
```

Published wheels include the native TACO reader. Building from the source
distribution requires a C++23 compiler, CMake, Ninja, pkg-config, libcurl
7.83 or newer, and OpenSSL 3 or newer.

```python
import taco

samples = taco.read("dataset.zip")
parts = taco.read(["part-0.zip", "part-1.zip"])

dataset = taco.open_dataset("dataset.zip")
targets = dataset.read(files="target.tif")
train = dataset.sql("SELECT * FROM dataset WHERE \"ml:split\" = 'train'")
```

`export()` writes the complete samples selected by a SQL query. The query may
use `dataset`, `sample`, or any declared metadata level. A match at a lower
level still copies the whole sample. Collection fields are inherited unless
they are replaced. For a remote source, only payloads from matching samples
are downloaded. Pass `overwrite=True` to replace an existing TACO output.

```python
source = "https://data.source.coop/major-tom/core-dem/"
taco.export(
    source,
    "core-dem-sample.zip",
    sql='SELECT * FROM sample ORDER BY id LIMIT 10',
)
```

Remote reads and exports show download progress in interactive terminals.
Writers show their build progress when opened with `progress=True`.

## GeoEnrich

`GeoEnrich` uses the public 10 km MajorTOM index on Source Cooperative by
default, so it needs no Earth Engine account. Place `MajorTOM(dist_km=10)` in
the same metadata level before using it:

```python
taco.Level(
    "sample",
    stac=taco.extensions.STAC(),
    majortom=taco.extensions.MajorTOM(dist_km=10),
    geoenrich=taco.extensions.GeoEnrich(
        ["elevation", "temperature", "admin_countries"],
    ),
)
```

Set `backend="earthengine"` explicitly to retain centroid-based Earth Engine
sampling. That backend requires `taco-eo[geoenrich]` and an authenticated Earth
Engine installation.

## Examples

Every example is self-contained, uses synthetic data, and writes its output in
the current directory.

Spatial and temporal metadata follow the fields of a STAC Item. `Temporal`
stores `datetime` or a `start_datetime`/`end_datetime` range, `Spatial` stores
the footprint and its `bbox`, and `STAC` stores both. Give a sample its grid
(`proj_code`, `proj_shape`, `proj_transform`) and the writer computes the
footprint, or give the footprint itself when no single grid describes it.

| Example | What it demonstrates |
| --- | --- |
| [`minimal.py`](examples/minimal.py) | Smallest possible single-file dataset |
| [`numpy_minimal.py`](examples/numpy_minimal.py) | NumPy image and mask assets with a train/test split |
| [`change_detection.py`](examples/change_detection.py) | Metadata on `before/` and `after/` folders |
| [`sequence.py`](examples/sequence.py) | Variable-length asset sequences |
| [`time_series.py`](examples/time_series.py) | Per-observation time and cloud metadata |
| [`geospatial.py`](examples/geospatial.py) | Compact STAC metadata and derived MajorTOM cells |
| [`stac_segmentation.py`](examples/stac_segmentation.py) | STAC footprints computed from UTM grids, with labels, bands, and scaling |
| [`oceantaco.py`](examples/oceantaco.py) | OceanTACO-inspired STAC footprints for irregular SWOT swaths and Argo collocations |
| [`partitioned.py`](examples/partitioned.py) | ZIP partitions and their TACOCAT catalog |
