Metadata-Version: 2.3
Name: canvodpy
Version: 0.2.1
Summary: Python ecosystem for GNSS-Transmissometry canopy VOD retrievals
Keywords: GNSS,VOD,vegetation,remote sensing,geodesy
Author: Nicolas François Bader
Author-email: Nicolas François Bader <nicolas.bader@tuwien.ac.at>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Dist: canvod-readers
Requires-Dist: canvod-auxiliary
Requires-Dist: canvod-grids
Requires-Dist: canvod-store
Requires-Dist: canvod-store-metadata
Requires-Dist: canvod-utils
Requires-Dist: canvod-viz
Requires-Dist: canvod-vod
Requires-Dist: marimo>=0.9.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: pint>=0.20
Requires-Dist: structlog>=23.0
Requires-Dist: pydantic>=2.0
Requires-Dist: tqdm>=4.65
Requires-Dist: tomli>=2.0.0
Requires-Dist: natsort>=8.0.0
Requires-Dist: dask[distributed]>=2026.1.1
Requires-Dist: mystmd>=1.8.0
Requires-Dist: docker>=7.1.0
Requires-Dist: howfairis>=0.13.0
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: palettable>=3.3.3
Requires-Dist: altair>=6.0.0
Requires-Dist: tabulate>=0.10.0
Requires-Dist: sqlglot>=29.0.1
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/nfb2021/canvodpy
Project-URL: Documentation, https://nfb2021.github.io/canvodpy/
Project-URL: Repository, https://github.com/nfb2021/canvodpy
Project-URL: Issues, https://github.com/nfb2021/canvodpy/issues
Description-Content-Type: text/markdown

# canvodpy

Umbrella package for unified GNSS VOD analysis.

## Overview

`canvodpy` is the unified entry point for the canVOD ecosystem. It provides
three levels of API:

- **Level 1:** One-line convenience functions (fastest path to results)
- **Level 2:** Object-oriented classes (structured workflows)
- **Level 3:** Low-level components (full control)

## Installation

```bash
# Installs canvodpy + all 7 sub-packages
uv pip install canvodpy
```

## Quick Start

### Level 1: Simple (One-Liners)

```python
from canvodpy import process_date, calculate_vod

# Process one day of data
data = process_date("Rosalia", "2025001")

# Calculate VOD
vod = calculate_vod("Rosalia", "canopy_01", "reference_01", "2025001")
```

### Level 2: Object-Oriented (More Control)

```python
from canvodpy import Site, Pipeline

# Create site and pipeline
site = Site("Rosalia")
pipeline = site.pipeline(aux_agency="ESA", n_workers=8)

# Process data
data = pipeline.process_date("2025001")

# Or process multiple days
for date, datasets in pipeline.process_range("2025001", "2025007"):
    print(f"Processed {date}")
```

### Level 3: Low-Level (Full Control)

```python
from canvod.readers import Rnxv3Obs
from canvod.auxiliary import Sp3File, ClkFile
from canvod.store import GnssResearchSite
from canvodpy.orchestrator import PipelineOrchestrator

# Direct access to all internals
site = GnssResearchSite("Rosalia")
orchestrator = PipelineOrchestrator(site, n_max_workers=12)
# ... custom processing ...
```

## Included Packages

Installing canvodpy provides access to all 7 packages:

- **canvod.readers** -- RINEX file parsing (v3.04)
- **canvod.auxiliary** -- Auxiliary data (SP3, CLK) handling
- **canvod.grids** -- Hemisphere grid structures
- **canvod.store** -- Icechunk data storage
- **canvod.vod** -- VOD calculation algorithms
- **canvod.viz** -- 2D/3D visualization
- **canvod.utils** -- Shared utilities

## Platform Support

| Platform | Status | Notes |
|----------|--------|-------|
| Linux | Full support | Recommended |
| macOS | Full support | Fully tested |
| Windows | WSL only | Native not supported (reserved `aux` name) |

## Configuration

Create a `.env` file in repository root (optional for NASA products):

```bash
# NASA CDDIS credentials (optional)
CDDIS_MAIL=your.email@example.com

# Data root directory (required)
GNSS_ROOT_DIR=/path/to/your/data
```

Without `.env`, canvodpy operates in ESA-only mode (COD, GFZ, ESA products).

## Documentation

[Centralized documentation](../docs/index.md)

## Development

See the [main repository README](../README.md) for workspace development setup.

## License

Apache License 2.0
