Metadata-Version: 2.4
Name: rpcfast
Version: 1.0.3
Summary: Fast RPC (rational polynomial camera) forward projection and inverse localization for batch remote sensing.
Project-URL: Homepage, https://github.com/shaodwei/rpcfast
Project-URL: Source, https://github.com/shaodwei/rpcfast
Project-URL: Tracker, https://github.com/shaodwei/rpcfast/issues
Author-email: Shaodong Wei <shaodwei@gmail.com>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Requires-Dist: numba>=0.57
Requires-Dist: numpy>=1.23
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: rasterio>=1.3; extra == 'dev'
Requires-Dist: rpcm; extra == 'dev'
Provides-Extra: geotiff
Requires-Dist: rasterio>=1.3; extra == 'geotiff'
Provides-Extra: validate
Requires-Dist: rpcm; extra == 'validate'
Description-Content-Type: text/markdown

# rpcfast package

This folder is a self-contained copy of `rpcfast`, a small Python library for
fast RPC camera projection and fixed-height localization.

Use this README as the operating guide for an AI assistant or another developer
who needs to call the library correctly.

## What This Library Does

- Reads RPC sidecar files such as `_RPC.txt`, `rpc.txt`, `.rpb`, and `_rpb.txt`.
- Writes standard RPC sidecar files as `.rpc`/text, `.rpb`, or WorldView XML.
- Optionally reads GeoTIFF RPC tags when `rasterio` is installed.
- Projects ground coordinates to image coordinates:
  `lon, lat, h -> col, row`.
- Localizes image coordinates back to ground coordinates at a fixed height:
  `col, row, h -> lon, lat, status`.
- Supports scalar inputs and NumPy arrays with normal broadcasting.
- Uses Numba kernels for batch speed.

## Install

From this folder:

```bash
pip install -e .
```

With optional GeoTIFF RPC tag support:

```bash
pip install -e ".[geotiff]"
```

With validation tools:

```bash
pip install -e ".[dev]"
```

## Correct Usage

```python
from rpcfast import read_rpc, project, localize

rpc = read_rpc("image.RPB")

lon = rpc.long_off
lat = rpc.lat_off
h = rpc.height_off

col, row = project(rpc, lon, lat, h)
lon2, lat2, status = localize(rpc, col, row, h)

if status != 0:
    raise RuntimeError(f"localize failed with status={status}")
```

Batch example:

```python
import numpy as np
from rpcfast import read_rpc, project, localize

rpc = read_rpc("image_RPC.txt")

lons = np.linspace(rpc.valid_lon_range[0], rpc.valid_lon_range[1], 10000)
lats = np.full_like(lons, rpc.lat_off)
hs = np.full_like(lons, rpc.height_off)

cols, rows = project(rpc, lons, lats, hs)
lons2, lats2, status = localize(rpc, cols, rows, hs)

if np.any(status != 0):
    bad = np.count_nonzero(status != 0)
    raise RuntimeError(f"{bad} points did not converge")
```

## Public API

```python
read_rpc(path) -> RPCModel
project(rpc, lon, lat, h) -> (col, row)
localize(rpc, col, row, h, max_iter=20, tol_px=1e-8) -> (lon, lat, status)
format_rpc(rpc, fmt="rpc") -> str
write_rpc(rpc, path, fmt=None) -> Path
```

`status` values:

- `0`: converged
- `1`: maximum iterations reached
- `2`: diverged or non-finite value encountered

`RPCModel` useful fields:

- `line_off`, `samp_off`
- `lat_off`, `long_off`, `height_off`
- `lat_scale`, `long_scale`, `height_scale`
- `valid_lon_range`, `valid_lat_range`, `valid_h_range`
- `source_format`, `source_path`
- `center_error_px`

`write_rpc()` infers output from the suffix by default: `.rpc`/`.txt` writes
keyed RPC text, `.rpb` writes DigitalGlobe-style RPB, and `.xml` writes a
WorldView-style `RPB/IMAGE` XML block. Pass `fmt="rpc"`, `"rpb"`, or `"xml"`
to override suffix inference.

## Important AI Rules

Follow these rules when modifying or using the code:

1. Read `SPEC.md` before changing projection math.
2. Do not change the 20-term monomial order in `rpcfast/kernel.py`.
3. Treat `row` as `LINE` and `col` as `SAMP`.
4. Pass longitude first, latitude second: `project(rpc, lon, lat, h)`.
5. `localize` assumes fixed height supplied by the caller. It does not use DEM,
   geoid correction, orthorectification, or stereo.
6. Do not import `rpcm`, `osgeo`, or GDAL in core runtime paths. They belong
   only in validation or tests.
7. Do not enable Numba `fastmath=True` unless the caller explicitly accepts
   approximate numerical behavior.
8. Always check `status` after `localize`.
9. Warm up Numba once before benchmarking; the first call includes JIT compile
   time.

## Validation

If sample RPC files are available, run:

```bash
pytest tests/ -m "not needs_rpcm"
pytest tests/
```

If this folder is used without the original test/data folders, make
a small smoke test with one real RPC file:

```python
from rpcfast import read_rpc, project, localize

rpc = read_rpc("your_file.RPB")
col, row = project(rpc, rpc.long_off, rpc.lat_off, rpc.height_off)
lon, lat, status = localize(rpc, col, row, rpc.height_off)

assert status == 0
assert abs(lon - rpc.long_off) < rpc.long_scale
assert abs(lat - rpc.lat_off) < rpc.lat_scale
```

## Known Implementation Notes

- The parser handles keyed RPC text/RPB files and GeoTIFF RPC tags.
- A SPEC-requested positional fallback for pure numbers-only dumps is not
  currently implemented. Keyed sample files are covered by the current tests.
- `center_error_px` is a diagnostic value. Some real RPC files have non-zero
  constant terms, so the center point may not equal `(SAMP_OFF, LINE_OFF)`
  exactly even when projection matches `rpcm`.

## Files In This Folder

```text
rpcfast/
  __init__.py
  model.py       RPCModel dataclass and 90-float flat array conversion
  parse.py       RPC text/RPB/GeoTIFF parser
  serialize.py   RPC text/RPB/XML writer
  kernel.py      Numba projection and localization kernels
  validate.py    optional rpcm comparison helpers and report CLI
  benchmark.py   throughput benchmark CLI
pyproject.toml   install metadata
SPEC.md          technical source of truth for math and parser rules
README.md        this AI/developer usage guide
```

## Author

Shaodong Wei
Doctor of Photogrammetry from Wuhan University
Postdoctoral Fellow at LGSI of Hong Kong Polytechnic University (now)

## License

MIT — see [LICENSE](LICENSE).
