Metadata-Version: 2.4
Name: topocurve
Version: 0.1.0
Summary: A package for processing digital elevation models.
Home-page: https://github.com/tschermer02/topoCurve1
Author: Taylor Schermer, Joel Nash, Nate Klema
Author-email: tschermer@fortlewis.edu, jxnash@fortlewis.edu, ntklema@fortlewis.edu
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2
Requires-Dist: scipy
Requires-Dist: zarr<2.13
Requires-Dist: numcodecs<0.12
Requires-Dist: Pillow
Requires-Dist: photutils<2.0,>=1.8
Requires-Dist: tifffile<2024.8
Requires-Dist: geotiff
Requires-Dist: scikit-learn
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![TopoCurve Logo](./TC-removebg-preview.png)

# TopoCurve
TopoCurve is a Python library for processing digital elevation models (DEM) stored in GeoTIFF format. This library provides functionalities to extract metadata, calculate principal curvatures and curvature features, as well as plot elevation values. It also includes spectral filtering capabilities for advanced DEM processing.

## Installation

To install TopoCurve, simply clone the repository and install the dependencies listed in `requirements.txt`:

```
git clone https://github.com/username/topo_curve.git
cd topo_curve
pip install -r requirements.txt
```

## Usage

```
from TopoCurve import TopoCurve
from SpectralFiltering import SpectralFiltering

# Instantiate TopoCurve object with a GeoTIFF file
dem = TopoCurve('path/to/your/file.tif')

# Instantiate SpectralFiltering object with a GeoTIFF file
spectral_filter = SpectralFiltering('path/to/your/file.tif')

# Apply FFT filtering
dx, dy, filtered_elevation = spectral_filter.FFT(filter, 'filtertype', alphaIn)

# Calculate principal curvatures and curvature features
K1, K2, KM, KG = dem.CurveCalc(ZFilt, dx, dy, kt)

# Plot and save elevation values
dem.plot(input_array, 'output_image.png')
```

## Example

```
from TopoCurve import TopoCurve
from SpectralFiltering import SpectralFiltering

# Instantiate TopoCurve object with a GeoTIFF file
dem = TopoCurve('references\DEM_files\Purgatory.tif')

# Instantiate SpectralFiltering object with a GeoTIFF file
spectral_filter = SpectralFiltering('references\DEM_files\Purgatory.tif')

# Apply FFT filtering
dx, dy, filtered_elevation = spectral_filter.FFT([190, 200], 'lowpass', 0)

# Calculate principal curvatures and curvature features
K1, K2, KM, KG = dem.CurveCalc(filtered_elevation, dx, dy, 0)

# Plot and save elevation values
dem.plot(filtered_elevation, 'output_image.png')
```

## API Documentation

### TopoCurve Class

#### `TopoCurve(tiff_file)`

Initialize the TopoCurve object with a GeoTIFF file.

- **Parameters:**
  - `tiff_file` (str): Path to the GeoTIFF file.

---

#### `CurveCalc(ZFilt, dx, dy, kt)`

Calculate principal curvatures and curvature features.

- **Parameters:**

  - `ZFilt` (numpy.ndarray): Filtered surface data.
  - `dx` (float): Grid spacing in the x direction.
  - `dy` (float): Grid spacing in the y direction.
  - `kt` (float): Threshold value.

- **Returns:**
  - `K1, K2` (tuple): Principal curvatures.
  - `KM` (tuple): Mean curvature.
  - `KG` (tuple): Gaussian curvature.

---

#### `plot(input, filename)`

Plot the elevation values and save the plot as an image file to reports/figures.

- **Parameters:**
  - `input` (numpy.ndarray): Input elevation values.
  - `filename` (str): Name of the output image file.

---

### Spectral Filtering Class

#### `SpectralFiltering(tiff_file)`

Initialize the SpectralFiltering object with a GeoTIFF file.

- **Parameters:**
  - `tiff_file` (str): Path to the GeoTIFF file.

#### `detrend()`

Detrend the elevation values using least squares plane fitting.

- **Returns:**
  - `Z_detrended` (numpy.ndarray): Detrended elevation values.
  - `plane` (numpy.ndarray): Trend component of the elevation values.

#### `mirror_dem()`

Mirror the elevation values.

- **Returns:**
  - `mirrored_array` (numpy.ndarray): Mirrored elevation values.

#### `tukeyWindow(alphaIn)`

Apply a Tukey window to the elevation values.

- **Arguments:**

  - `alphaIn` (float): Parameter controlling the shape of the Tukey window.

- **Returns:**
  - `tukey_array` (numpy.ndarray): Elevation values after applying the Tukey window.

#### `padding(alphaIn)`

Pad the elevation values.

- **Arguments:**

  - `alphaIn` (float): Parameter controlling the shape of the Tukey window.

- **Returns:**
  - `padded_window_array` (numpy.ndarray): Padded elevation values.

#### `FFT(filter, filterType, alphaIn)`

Apply FFT filtering to the elevation values.

- **Arguments:**

  - `filter` (float): Filter parameter.
  - `filterType` (str): Type of filter ('lowpass' or 'highpass').
  - `alphaIn` (float): Parameter controlling the shape of the Tukey window.

- **Returns:**
  - `dx` (float): Grid spacing in the x direction.
  - `dy` (float): Grid spacing in the y direction.
  - `ZFilt` (numpy.ndarray): Filtered elevation values.

---

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Project Organization
```
â”œâ”€â”€ LICENSE              
â”œâ”€â”€ Makefile             
â”œâ”€â”€ README.md           
â”œâ”€â”€ TC-removebg-preview.png <- Project logo.

â”œâ”€â”€ docs/                <- Documentation source files for the project:
â”‚   â”œâ”€â”€ Makefile        
â”‚   â”œâ”€â”€ commands.rst     
â”‚   â”œâ”€â”€ conf.py          
â”‚   â”œâ”€â”€ getting-started.rst 
â”‚   â”œâ”€â”€ index.rst        
â”‚   â””â”€â”€ make.bat        

â”œâ”€â”€ references/          <- Supporting files and research materials:
â”‚   â”œâ”€â”€ DEM_files/       <- Contains Digital Elevation Model (DEM) test files.
â”‚   â”œâ”€â”€ paper.md         <- Markdown file with detailed project research or report.
â”‚   â””â”€â”€ .gitkeep        

â”œâ”€â”€ reports/             <- Generated analyses and reports:
â”‚   â”œâ”€â”€ figures/         <- Directory for report graphics and visualizations.
â”‚   â””â”€â”€ .gitkeep    

â”œâ”€â”€ requirements.txt     
â”œâ”€â”€ setup.py             
â”œâ”€â”€ src/                 <- Source code for the project:
â”‚   â”œâ”€â”€ __init__.py      
â”‚   â”œâ”€â”€ SpectralFiltering.py <- Contains FFT-based spectral filtering methods.
â”‚   â”œâ”€â”€ TopoCurve.py     <- Core script for curvature calculations and DEM processing.
â”‚   â”œâ”€â”€ code_play.py     <- Experimental script with templates for further development.
â”‚   â””â”€â”€ test.py          <- Unit tests to validate functionality.

â”œâ”€â”€ test_environment.py  
â””â”€â”€ tox.ini              
```

## Credits

- **Principal Contributor:** [Sonie Taylor Schermer](https://github.com/tschermer02)
- **Contributions:**  [Joel Nash](https://github.com/jxnash), [Nate Klema](https://github.com/ntklema), [Leif Karlstrom](https://github.com/leifkarlstrom)



<p><small>Project based on the <a target="_blank" href="https://drivendata.github.io/cookiecutter-data-science/">cookiecutter data science project template</a>. #cookiecutterdatascience</small></p>
```
