Metadata-Version: 2.4
Name: viewtif
Version: 0.2.4
Summary: Lightweight GeoTIFF, NetCDF, HDF/HDF5, and Esri File Geodatabase (.gdb) viewer with optional shapefile overlay. NetCDF and cartopy support available via pip install viewtif[netcdf].
Project-URL: Homepage, https://github.com/nkeikon/tifviewer
Project-URL: Source, https://github.com/nkeikon/tifviewer
Project-URL: Issues, https://github.com/nkeikon/tifviewer/issues
Author: Keiko Nomura
License: MIT
Requires-Python: >=3.9
Requires-Dist: click>=8.1
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.23
Requires-Dist: pyside6>=6.5
Requires-Dist: rasterio>=1.3
Provides-Extra: geo
Requires-Dist: geopandas>=0.13; extra == 'geo'
Requires-Dist: shapely>=2.0; extra == 'geo'
Provides-Extra: netcdf
Requires-Dist: cartopy>=0.22; extra == 'netcdf'
Requires-Dist: netcdf4>=1.6; extra == 'netcdf'
Requires-Dist: pandas>=2.0; extra == 'netcdf'
Requires-Dist: xarray>=2023.1; extra == 'netcdf'
Description-Content-Type: text/markdown

# viewtif
[![Downloads](https://static.pepy.tech/badge/viewtif)](https://pepy.tech/project/viewtif)
[![PyPI version](https://img.shields.io/pypi/v/viewtif)](https://pypi.org/project/viewtif/)

A lightweight GeoTIFF viewer for quick visualization directly from the command line.  

You can visualize single-band GeoTIFFs, RGB composites, HDF, NetCDF files and shapefile overlays in a simple Qt-based window.

## Installation

```bash
pip install viewtif
```
> **Note:** On Linux, you may need python3-tk, libqt5gui5, or PySide6 dependencies.
> 
>`viewtif` requires a graphical display environment.  
> It may not run properly on headless systems (e.g., HPC compute nodes or remote servers without X11 forwarding).

### Optional features
#### Shapefile overlay support
```bash
pip install "viewtif[geo]"
```
> **Note:** For macOS(zsh) users:
> Make sure to include the quotes, or zsh will interpret it as a pattern.

#### HDF/HDF5 support 
```bash
brew install gdal     # macOS
sudo apt install gdal-bin python3-gdal  # Linux
pip install GDAL
```
> **Note:** GDAL is required to open `.hdf`, .`h5`, and `.hdf5` files. If it’s missing, viewtif will display: `RuntimeError: HDF support requires GDAL.`

#### NetCDF support 
```bash
brew install  "viewtif[netcdf]"
```
> **Note:** For enhanced geographic visualization with map projections, coastlines, and borders, install with cartopy: `pip install "viewtif[netcdf]"` (cartopy is included in the netcdf extra). If cartopy is not available, netCDF files will still display with standard RGB rendering.
## Quick Start
```bash
# View a GeoTIFF
viewtif ECOSTRESS_LST.tif

# View an RGB composite
viewtif --rgbfiles \
  HLS_B04.tif \
  HLS_B03.tif \
  HLS_B02.tif

# View with shapefile overlay
viewtif ECOSTRESS_LST.tif \
  --shapefile Zip_Codes.shp
```
### Update in v1.0.6: HDF/HDF5 support
`viewtif` can open `.hdf`, `.h5`, and `.hdf5` files that contain multiple subdatasets. When opened, it lists available subdatasets and lets you view one by index. You can also specify a band to display (default is the first band) or change bands interactively with '[' and ']'.
```bash
# List subdatasets
viewtif AG100.v003.33.-107.0001.h5

# View a specific subdataset
viewtif AG100.v003.33.-107.0001.h5 --subset 1

# View a specific subdataset and band
viewtif AG100.v003.33.-107.0001.h5 --subset 1 --band 3
```
> **Note:** Some datasets (perhaps the majority of .hdf files) lack CRS information encoded, so shapefile overlays may not work. In that case, viewtif will display:
`[WARN] raster lacks CRS/transform; cannot place overlays.`

### Update in v1.0.7: File Geodatabase (.gdb) support
`viewtif` can now open raster datasets stored inside Esri File Geodatabases (`.gdb`). When you open a .gdb directly, `viewtif`` will list available raster datasets first, then you can choose one to view.

Most Rasterio installations already include the OpenFileGDB driver, so .gdb datasets often open without installing GDAL manually.

If you encounter: RuntimeError: GDB support requires GDAL, install GDAL as shown above to enable the driver.

```bash
# List available raster datasets
viewtif /path/to/geodatabase.gdb

# Open a specific raster
viewtif "OpenFileGDB:/path/to/geodatabase.gdb:RasterName"
```
> **Note:** If multiple raster datasets are present, viewtif lists them all and shows how to open each. The .gdb path and raster name must be separated by a colon (:).

### Update in v1.0.7: Large raster safeguard
As of v1.0.7, `viewtif` automatically checks the raster size before loading.  
If the dataset is very large (e.g., >20 million pixels), it will pause and warn that loading may freeze your system.  
You can proceed manually or rerun with the `--scale` option for a smaller, faster preview.

### Update in v0.2.2: NetCDF support with optional cartopy visualization
`viewtif` now supports NetCDF (`.nc`) files with xarray and optional cartopy geographic visualization.

#### Installation with NetCDF support
```bash
pip install "viewtif[netcdf]"
```

#### Examples
```bash
viewtif data.nc
```

## Controls
| Key                  | Action                                  |
| -------------------- | --------------------------------------- |
| `+` / `-` or mouse / trackpad            | Zoom in / out                           |
| Arrow keys or `WASD` | Pan                                     |
| `C` / `V`            | Increase / decrease contrast            |
| `G` / `H`            | Increase / decrease gamma               |
| `M`                  | Toggle colormap (`viridis` ↔ `magma`)   |
| `[` / `]`            | Previous / next band (or time step)     |
| `R`                  | Reset view                              |

## Features
- Command-line driven GeoTIFF viewer.
- Supports single-band, RGB composite, HDF/HDF5 subdatasets, and NetCDF.
- Optional shapefile overlay for geographic context.
- Adjustable contrast, gamma, and colormap.
- Fast preview using rasterio and PySide6.

## Example Data
- ECOSTRESS_LST.tif
- Zip_Codes.shp and associated files
- HLS_B04.tif, HLS_B03.tif, HLS_B02.tif (RGB sample)
- AG100.v003.33.-107.0001.h5 (HDF5 file)

## Credit & License
`viewtif` was inspired by the NASA JPL Thermal Viewer — Semi-Automated Georeferencer (GeoViewer v1.12) developed by Jake Longenecker (University of Miami Rosenstiel School of Marine, Atmospheric & Earth Science) while at the NASA Jet Propulsion Laboratory, California Institute of Technology, with inspiration from JPL’s ECOSTRESS geolocation batch workflow by Andrew Alamillo. The original GeoViewer was released under the MIT License (2025) and may be freely adapted with citation.

## Citation
Longenecker, Jake; Lee, Christine; Hulley, Glynn; Cawse-Nicholson, Kerry; Purkis, Sam; Gleason, Art; Otis, Dan; Galdamez, Ileana; Meiseles, Jacquelyn. GeoViewer v1.12: NASA JPL Thermal Viewer—Semi-Automated Georeferencer User Guide & Reference Manual. Jet Propulsion Laboratory, California Institute of Technology, 2025. PDF.

## License
This project is released under the MIT License.

## Contributors
- [@HarshShinde0](https://github.com/HarshShinde0) — added mouse-wheel and trackpad zoom support; added NetCDF support with [@nkeikon](https://github.com/nkeikon) 
- [@p-vdp](https://github.com/p-vdp) — added File Geodatabase (.gdb) raster support