Metadata-Version: 2.4
Name: jrsrpname
Version: 0.1.0
Summary: Python implementation of the QVF satellite imagery file-naming convention (Flood & Danaher, 2013)
Author-email: Robert Denham <robert.denham@uq.edu.au>
License-File: AUTHORS.md
License-File: LICENSE.txt
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# jrsrpname

![Pipeline Status](https://gitlab.com/jrsrp/sys/jrsrpname/badges/main/pipeline.svg)
![Security](https://gitlab.com/jrsrp/sys/jrsrpname/badges/main/pipeline.svg?job=secret_gatekeeper&key_text=secrets)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
[![Latest Release](https://img.shields.io/gitlab/v/tag/jrsrp/sys/jrsrpname?label=version&color=blue)](https://gitlab.com/jrsrp/sys/jrsrpname/-/tags)

A Python implementation of the **QVF** file-naming convention for large satellite imagery
archives, as described in:

> Flood, N. and Danaher, T. (2013). *A File Naming Convention for a Large Satellite Imagery
> Archive: QVF -- a case study*.
> [doi:10.6084/m9.figshare.875298.v1](https://doi.org/10.6084/m9.figshare.875298.v1)

```bibtex
@article{Flood2013,
    author = "Neil Flood and Tim Danaher",
    title = "{A File Naming Convention for a Large Satellite Imagery Archive: QVF - a case study}",
    year = "2013",
    month = "12",
    url = "https://figshare.com/articles/journal_contribution/A_File_Naming_Convention_for_a_Large_Satellite_Imagery_Archive_QVF_a_case_study/875298",
    doi = "10.6084/m9.figshare.875298.v1"
}
```

## Provenance

`jrsrpname` is an independent reimplementation, built from the naming-convention description
published in the paper above. It is not a port of, and shares no code with, any existing
implementation.

The author has prior familiarity with an existing closed-source implementation of this
convention (also referred to as `qvf.py`), whose copyright ownership is not clearly established.
To avoid any ambiguity about derivation, `jrsrpname` deliberately uses a different name and a
different internal design, and was written directly from the published paper rather than from
that source.

Most of the implementation was written with the assistance of Claude (Anthropic). Unlike the
author, Claude was never given, and did not access, view, or otherwise reference `qvf.py` or any
other prior implementation of this convention at any point -- its only source for the
naming/parsing specification was the published paper above, fetched directly from figshare.

## Installation

```sh
python3 -m pip install jrsrpname
```

## Usage

Usage follows closely to that as described in Flood, N. and Danaher, T. (2013), but uses
a more object oriented approach. The basic approach is to parse a string representing
a QVF filename:

```python
from jrsrpname import QVFName
name = QVFName.parse("l5tmre_p090r079_20090914_dbgm6.img")
```

The name will then have as members the described `what`, `where`, `when`, `processing`, `suffix`
components:

```python
print(name.what)
# l5tmre
print(name.where)
# p090r079
print(name.when)
# 20090914
print(name.processing)
# dbgm6
print(name.suffix)
# img
```

Modifications to any of these are done with the `replace` method:

```python
newname = name.replace(where='qld')
print(newname)
# l5tmre_qld_20090914_dbgm6.img
```



## Development

This project uses [`uv`](https://docs.astral.sh/uv/).

```sh
# install dev deps
uv sync

# run tests
uv run pytest tests/

# lint / format
uv run ruff check .
uv run ruff format .

# install git hooks (required before contributing -- see CONTRIBUTING.md)
uv run pre-commit install
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for more.
