Metadata-Version: 2.4
Name: rasteric
Version: 2.0.0
Summary: A Python geospatial library for raster preprocessing, analysis, visualization, and modeling
Home-page: https://github.com/tnmthai/rasteric
Author: Thai Tran
Author-email: me@tnmthai.com
License: MIT
Project-URL: Bug Tracker, https://github.com/tnmthai/rasteric/issues
Project-URL: repository, https://github.com/tnmthai/rasteric
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: rasterio>=1.0
Requires-Dist: matplotlib>=3.0
Requires-Dist: shapely>=1.7
Requires-Dist: geopandas>=0.9
Requires-Dist: numpy>=1.18
Requires-Dist: pandas>=1.0
Requires-Dist: scikit-learn>=0.24
Requires-Dist: scikit-image
Requires-Dist: Pillow
Requires-Dist: rasterstats
Requires-Dist: scipy
Dynamic: author
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Rasteric

**Rasteric** is a Python geospatial library designed for raster preprocessing, analysis, visualization, and modeling. It simplifies common GIS workflows with easy-to-use functions built on top of Rasterio and GeoPandas.

## Installation

```bash
pip install rasteric
```

Dependencies are installed automatically:

- rasterio, geopandas, shapely
- numpy, pandas, matplotlib, scipy
- scikit-learn, scikit-image
- rasterstats, Pillow

## Requirements

- **Python** >= 3.8

## Supported Data Formats

- **Raster**: GeoTIFF, TIFF
- **Vector**: Shapefiles, GeoJSON
- **Tabular**: CSV with spatial attributes (latitude/longitude)

## Typical Use Cases

- Satellite image preprocessing (Sentinel-2, Landsat)
- NDVI and vegetation analysis
- Land-use / land-cover mapping
- Agricultural monitoring
- Raster-vector data extraction
- Geospatial machine learning data preparation
- Time-series crop monitoring
- Change detection

## Quick Start

```python
from rasteric import (plot, clip, ndvi, evi, stack, extract, mosaic, calc,
                      change_detect, timeseries, cloudmask, classify, sample)

# Visualize
plot('sentinel2.tif', bands=(4, 3, 2), brightness_factor=4)

# Vegetation indices
ndvi('sentinel2.tif', 'ndvi.tif', red_band=3, nir_band=4)
evi('sentinel2.tif', 'evi.tif', nir_band=4, red_band=3, blue_band=2)

# Mosaic tiles
mosaic('tiles/', 'merged.tif')

# Band math
calc('(B8 - B4) / (B8 + B4)', inputs={'B8': 'nir.tif', 'B4': 'red.tif'}, output='ndvi.tif')

# Change detection
result = change_detect('ndvi_jan.tif', 'ndvi_jul.tif', 'change.tif', threshold=0.2)

# Time-series
df = timeseries('ndvi_folder/', output_csv='ndvi_ts.csv')

# Cloud masking (Sentinel-2)
cloudmask('sentinel2.tif', 'cloud_free.tif', method='scl')

# Classification
classify('image.tif', 'classes.tif', method='kmeans', n_clusters=5)

# ML training data
df = sample('sentinel2.tif', 'training.shp', 'samples.csv', label_column='class')
```

## Functions

### Vegetation Indices

| Function | Description |
|---|---|
| `ndvi(raster, out, red, nir)` | Normalized Difference Vegetation Index |
| `evi(raster, out, nir, red, blue)` | Enhanced Vegetation Index |
| `savi(raster, out, nir, red, L)` | Soil-Adjusted Vegetation Index |
| `ndwi(raster, out, green, swir)` | Normalized Difference Water Index |
| `gndvi(raster, out, nir, green)` | Green NDVI (chlorophyll sensitivity) |
| `ndmi(raster, out, nir, swir)` | Normalized Difference Moisture Index |

### Data Handling

| Function | Description |
|---|---|
| `stack(folder, out)` | Stack multiple rasters into multi-band file |
| `mosaic(folder, out, method)` | Merge raster tiles into one raster |
| `mergecsv(path, out)` | Merge CSV files in a directory |
| `clip(raster, shp, out)` | Clip raster by shapefile |
| `reproject(raster, out, crs)` | Reproject to different CRS |
| `resample(raster, out, factor)` | Resample to new resolution |

### Raster Calculator

| Function | Description |
|---|---|
| `calc(expr, inputs, out)` | Band math with named inputs |
| `bandmath(raster, equation, out)` | Band math with B1, B2, ... |

### Analysis

| Function | Description |
|---|---|
| `zonalstats(raster, vector, stats)` | Zonal statistics for polygons |
| `stats(raster)` | Basic statistics (min, max, mean, std) |
| `fillnodata(raster, out)` | Fill NoData via interpolation |

### Time-Series & Change Detection

| Function | Description |
|---|---|
| `timeseries(folder, out_csv, band, stat)` | Analyze raster time-series |
| `change_detect(img1, img2, out, method, threshold)` | Detect changes between dates |

### Cloud Masking

| Function | Description |
|---|---|
| `cloudmask(raster, out, method)` | Sentinel-2 cloud masking (QA60 or SCL) |

### Image Classification

| Function | Description |
|---|---|
| `classify(raster, out, method, n_clusters)` | K-Means or Random Forest classification |
| `texture(raster, out, band, properties)` | GLCM texture features |

### ML Preparation

| Function | Description |
|---|---|
| `sample(raster, shp, out_csv, label)` | Extract training samples from raster |
| `train_test_split(csv, test_size)` | Split samples into train/test sets |

### Extraction

| Function | Description |
|---|---|
| `extract(data, shp, out_csv)` | Extract raster values at vector locations |
| `align_to_shp(tif, shp, out)` | Reproject raster to match shapefile CRS |

### Visualization

| Function | Description |
|---|---|
| `plot(file, bands, cmap, title, ax, brightness)` | Display raster with band selection |
| `contour(file)` | Overlay contour lines |
| `hist(file, bin, title)` | Histogram of pixel values |
| `thumbnail(raster, out_png, bands, size)` | Quick PNG thumbnail |

### Conversion

| Function | Description |
|---|---|
| `convras(raster, out_shp)` | Raster to vector polygons |

### Utilities

| Function | Description |
|---|---|
| `convpath(path)` | Cross-platform path conversion |
| `bandnames(raster, names)` | Update band descriptions |
| `haversine(lon1, lat1, lon2, lat2)` | Great-circle distance |

### Sentinel-2

```python
from rasteric import process_sen2

# Full pipeline: JP2→TIFF, resample, stack, cloud removal
process_sen2('source/', 'output/')
```

## Contributing

- **Repository**: [github.com/tnmthai/rasteric](https://github.com/tnmthai/rasteric)
- **Issues**: [github.com/tnmthai/rasteric/issues](https://github.com/tnmthai/rasteric/issues)
- **PyPI**: [pypi.org/project/rasteric](https://pypi.org/project/rasteric/)

## License

MIT License
