Metadata-Version: 2.4
Name: rasteric
Version: 1.2.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: rasterstats
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
- scikit-learn
- rasterstats
- scipy (optional, for gap filling)

## 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

## Quick Start

```python
from rasteric import plot, clip, ndvi, evi, stack, extract, mosaic, calc

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

# Clip raster to study area
clip('raster.tif', 'boundary.shp', 'clipped.tif')

# Compute NDVI
ndvi('sentinel2.tif', 'ndvi_output.tif', red_band=3, nir_band=4)

# Compute Enhanced Vegetation Index
evi('sentinel2.tif', 'evi_output.tif', nir_band=4, red_band=3, blue_band=2)

# Stack band files into a single multi-band raster
stack('bands_folder/', 'stacked.tif')

# Merge tiles into one raster
mosaic('tiles/', 'merged.tif')

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

# Extract raster values at vector points
extract('raster.tif', 'points.shp', 'extracted.csv')
```

## Functions

### Vegetation Indices

| Function | Description |
|---|---|
| `ndvi(raster_file, output_file, red_band, nir_band)` | Normalized Difference Vegetation Index |
| `evi(raster_file, output_file, nir_band, red_band, blue_band)` | Enhanced Vegetation Index |
| `savi(raster_file, output_file, nir_band, red_band, L)` | Soil-Adjusted Vegetation Index |
| `ndwi(raster_file, output_file, green_band, swir_band)` | Normalized Difference Water Index |
| `gndvi(raster_file, output_file, nir_band, green_band)` | Green NDVI (chlorophyll sensitivity) |
| `ndmi(raster_file, output_file, nir_band, swir_band)` | Normalized Difference Moisture Index |

### Data Handling

| Function | Description |
|---|---|
| `stack(input_folder, output_file)` | Stack multiple rasters into a single multi-band file |
| `mosaic(input_folder, output_file, method)` | Merge raster tiles into one continuous raster |
| `mergecsv(path, outfile)` | Merge all CSV files in a directory |
| `clip(raster_file, shapefile, output_file)` | Clip a raster using a shapefile geometry |
| `reproject(input_raster, output_raster, target_crs)` | Reproject a raster to a different CRS |
| `resample(input_raster, output_raster, scale_factor)` | Resample raster to a new resolution |

### Raster Calculator

| Function | Description |
|---|---|
| `calc(expression, inputs, output_file)` | Evaluate band math expression with named inputs |
| `bandmath(input_file, equation, output_file)` | Evaluate band math using B1, B2, ... band numbers |

### Analysis

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

### Extraction

| Function | Description |
|---|---|
| `extract(input_data, shp, output_csv)` | Extract raster values for vector features or CSV points |
| `align_to_shp(input_tif, source_shp, output_tif)` | Reproject raster to match a shapefile's CRS |

### Visualization

| Function | Description |
|---|---|
| `plot(file, bands, cmap, title, ax, brightness_factor)` | Display raster with band selection and brightness |
| `contour(file)` | Overlay contour lines on a raster |
| `hist(file, bin, title)` | Plot histogram of raster pixel values |

### Conversion

| Function | Description |
|---|---|
| `convras(raster_file, output_shapefile)` | Convert raster to vector polygons |

### Utilities

| Function | Description |
|---|---|
| `convpath(file_path)` | Convert backslashes to forward slashes |
| `bandnames(input_raster, band_names)` | Update band descriptions |
| `haversine(lon1, lat1, lon2, lat2)` | Great-circle distance between two points |

## Sentinel-2 Support

Rasteric includes dedicated Sentinel-2 processing functions:

```python
from rasteric import process_sen2

# Convert JP2 to TIFF, resample bands, stack, and remove clouds
process_sen2('source_folder/', 'output_folder/')
```

## Roadmap

### v1.3 (planned)
- `change_detect()` — Detect changes between two rasters
- `timeseries()` — Time-series analysis of raster folder
- `cloudmask()` — Cloud masking for Sentinel-2

### v2.0 (planned)
- `classify()` — Image classification (Random Forest, K-Means)
- `texture()` — GLCM texture features
- `sample()` — ML training data preparation

## Contributing

We welcome contributions and issue reports!

- **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
