Metadata-Version: 2.4
Name: naturtag
Version: 0.9.2
Summary: Tag your nature photos with iNat taxonomy and observation metadata
Project-URL: Homepage, https://github.com/pyinat/naturtag
Project-URL: Repository, https://github.com/pyinat/naturtag
Project-URL: Documentation, https://naturtag.readthedocs.io
Author: Jordan Cook
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.13
Requires-Dist: attrs>=21.2
Requires-Dist: click>=8.0
Requires-Dist: pillow>=10.0
Requires-Dist: pyexiv2>=2.10
Requires-Dist: pyinaturalist-convert[db]>=0.8.2
Requires-Dist: pyinaturalist>=0.21.1
Requires-Dist: pyqtdarktheme-fork>=2.3.6
Requires-Dist: pyside6==6.10.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: qtawesome~=1.4.0
Requires-Dist: requests-ratelimiter<0.9,>=0.6
Requires-Dist: sqlalchemy~=2.0.47
Description-Content-Type: text/markdown

# Naturtag

[![Build status](https://github.com/pyinat/naturtag/actions/workflows/test.yml/badge.svg)](https://github.com/pyinat/naturtag/actions)
[![Codecov](https://codecov.io/gh/pyinat/naturtag/graph/badge.svg?token=KB6A8LPMB1)](https://codecov.io/gh/pyinat/naturtag)
[![Documentation status](https://readthedocs.org/projects/naturtag/badge/?version=stable)](https://naturtag.readthedocs.io/en/stable/)
[![GitHub issues](https://img.shields.io/github/issues/pyinat/naturtag)](https://github.com/pyinat/naturtag/issues)
[![PyPI](https://img.shields.io/pypi/v/naturtag?color=blue)](https://pypi.org/project/naturtag)
[![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/naturtag)](https://pypi.org/project/naturtag)


<!-- RTD-IGNORE -->
<br />

[![](assets/icons/naturtag-gh-preview.png)](https://naturtag.readthedocs.io)

## Contents
- [Summary](#summary)
- [Use Cases](#use-cases)
- [Installation](#installation)
- [Usage](#usage)
  - [GUI](#gui)
  - [CLI](#cli)
  - [Library](#library)
- [Development Status](#development-status)
<!-- END-RTD-IGNORE -->

## Summary
Naturtag is a tool for nature photographers that adds useful metadata to describe the organisms in
your photos. It includes a **desktop application**, a **command-line interface**, and can also be
used as a **python library**. It is mainly intended for use with [iNaturalist](https://www.inaturalist.org), but can also be used independently.

Naturtag gathers observation metadata (for iNaturalist observation photos), or just taxonomy metadata (for everything else). It then embeds this information in your local photo collection using
[EXIF](https://en.wikipedia.org/wiki/Exif),
[XMP](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform), and
[Simple Darwin Core](https://dwc.tdwg.org/simple) metadata.

## Use Cases
This image metadata has a variety of uses, including:

### Local photo organization
Naturtag can tag your photos with **hierarchical keywords** (aka structured keywords), which
are supported by some photo viewers/editors like
[**Lightroom**](https://millennialdiyer.com/articles/photography/lightroom-keyword-hierarchy/),
[**FastPictureViewer**](https://www.fastpictureviewer.com),
[**Photo Mechanic**](https://www.photometadata.org/META-Tutorials-Photo-Mechanic-Applying-Keywords),
[**digiKam**](https://www.digikam.org), and
[**XnViewMP**](https://www.xnview.com/en/xnviewmp).

This basically gives you a taxonomic tree for browsing and filtering your photos.

<details>
<summary><b>Example in XnView</b></summary>

![Hierarchical keyword taxonomy tree in XnView](assets/screenshots/xnview.png)
</details>

### Photo hosting
Naturtag can also simplify tagging photos for photo hosting sites like Flickr. For that use case, this
tool generates semi-structured keywords in the same format as
[iNaturalist's Flickr Tagger](https://www.inaturalist.org/taxa/flickr_tagger).

Example search using these tags: https://www.flickr.com/photos/tags/taxonomy:class=arachnida

<details>
<summary><b>Example of taxonomy tags on Flickr</b></summary>

![Taxonomy tags displayed on a Flickr photo](assets/screenshots/flickr.png)
</details>

## Installation
Packages are available on [GitHub Releases](https://github.com/pyinat/naturtag/releases) for
Windows, macOS, and most major Linux distributions. See
[Installation](https://naturtag.readthedocs.io/en/stable/installation.html) for instructions.

It can also be installed from PyPI. Example with [`uv`](https://docs.astral.sh/uv):
```sh
uv tool install naturtag
```

## Usage

### GUI
Naturtag is primarily a desktop application. It includes an interface for selecting and tagging images:

![Image selector interface showing file browser and tagged photos](assets/screenshots/image-selector.png)

And tools to search and browse species and observations to tag your images with:

![Taxon search interface](assets/screenshots/taxon-search.png)

![Observation browser interface](assets/screenshots/observation-browser.png)

The general workflow currently looks like:
* Upload an observation to iNaturalist
* Load your local photos in Naturtag
* Select your observation in Naturtag and tag images

After initial tagging, future updates are simpler:
* Load local photos in Naturtag (optionally for multiple observations/taxa)
* Click 'Refresh tags' to fetch any updates from iNaturalist and apply to your local photos

Alternatively, without iNaturalist:
* Load your local photos in Naturtag
* Select a taxon in Naturtag and tag images

See [Application Guide](https://naturtag.readthedocs.io/en/stable/app.html) for more details.

Bulk tagging features (for handling multiple observations/taxa at a time) are planned for a future release.

### CLI
Naturtag also includes a command-line interface. It takes an observation or species, plus some image
files, and generates EXIF and XMP metadata to write to those images.

Example:
```bash
# Tag images with metadata from observation ID 5432
nt tag -o 5432 img1.jpg img2.jpg

# Refresh previously tagged images with latest observation and taxonomy metadata
nt refresh -r ~/observations
```
You can see it in action here:
[![asciicast](https://asciinema.org/a/0a6gzpt7AI9QpGoq0OGMDOxqi.svg)](https://asciinema.org/a/0a6gzpt7AI9QpGoq0OGMDOxqi)

See [CLI documentation](https://naturtag.readthedocs.io/en/stable/cli.html) for more details.

### Library
You can also import `naturtag` as a python library, and use its main features in your own scripts or
applications. Basic example:
```python
from naturtag import tag_images, refresh_tags

# Tag images with full observation metadata
tag_images(['img1.jpg', 'img2.jpg'], observation_id=5432)

# Refresh previously tagged images with latest observation and taxonomy metadata
refresh_tags(['~/observations/'], recursive=True)
```

See [API Reference](https://naturtag.readthedocs.io/en/stable/reference.html) for more details.

## Development Status
* See [Issues](https://github.com/pyinat/naturtag/issues) for planned features and current progress.
* If you have any problems, suggestions, or questions about naturtag, you can:
  * [Create an issue](https://github.com/pyinat/naturtag/issues/new/choose)
  * [Create a discussion](https://github.com/orgs/pyinat/discussions) (for more open-ended questions)
  * Ping me (**@jcook**) on the [iNaturalist Community Forum](https://forum.inaturalist.org/c/general/14).
* Many features of naturtag have been added upstream to other libraries I maintain. You can follow development of those projects here:
  * [pyinaturalist](https://github.com/pyinat/pyinaturalist)
  * [pyinaturalist-convert](https://github.com/pyinat/pyinaturalist-convert)
  * [requests-cache](https://github.com/requests-cache/requests-cache)
  * [requests-ratelimiter](https://github.com/JWCook/requests-ratelimiter)
