project/model/README.md

LongMemory-Geo

A local CPU package for RGB overhead imagery. It combines a retained DOTA-pretrained YOLO26n oriented detector with a seven-class fine-tuned YOLO26n semantic segmenter. Detector fine-tuning candidates regressed and were rejected. Check model.json for checkpoint identities, training provenance, supported classes and calibrated detection thresholds.

Extract the delivery ZIP, then run from its root. Install the pinned CPU dependencies with python -m pip install -r model/requirements.lock (Python 3.13):

from inference import Model
from PIL import Image
import json

model = Model('model')
result = model.predict('/absolute/path/to/rgb_image.tif')
Image.fromarray(result['regions']).save('regions.png')
with open('objects.json', 'w') as stream:
    json.dump(result['objects'], stream, indent=2)

Inputs are uint8 RGB NumPy arrays or RGB/RGBA images. TIFF input requires three uint8 RGB bands. Inputs retain their native scale. Detection boxes use source-image pixel coordinates: obb_polygon contains four ordered corners, and bbox is [x, y, width, height]. Semantic output has the original image dimensions and stable canonical IDs. Nodata, transparent pixels and fully black pixels receive ignore ID 255. This conservative rule can exclude valid dark pixels. The output mask does not automatically copy TIFF georeferencing.

Detection supports bridge, vehicle, large vehicle, aircraft, vessel and storage tank. Segmentation supports building, road, water, vegetation, agricultural area, bare ground and developed area. Railway, parking area and construction are unsupported. Bare-ground recognition and bridge recall require particular caution; per-class results are more informative than a single aggregate score.

Large images use padded 1024-pixel tiles with 25% nominal overlap and edge-aligned final windows. Cross-tile detections use oriented NMS. Semantic overlaps select the tile with the most surrounding context, preserving categorical labels. This requires the full RGB image, a uint8 mask and a uint16 ownership array in RAM. It is not a streaming gigapixel implementation. Alternative fusion methods and multiscale inference are not benchmarked.

confidence=0.3 overrides all calibrated detection thresholds. Leave it unset to use validation-calibrated per-class thresholds. No semantic confidence score is claimed.

The primary supported interface uses PyTorch CPU. See EXPORT.json for ONNX export/parity outcomes. An exported graph is available only if its parity check passed. ONNX graphs use fixed 1×3×1024×1024 RGB float inputs in [0,1]; framework postprocessing and canonical remapping remain necessary. The Model interface loads PyTorch checkpoints.

Reproduction commands require the original project checkout and fresh output paths:

python -m training.package_model --report training/runs/2026-10-30-semantic-full/GATE.json
python -m evaluation.export_model --model-dir model
python -m evaluation.full_eval --model-dir model --output evaluation/runs/final-test

Packaging and export refuse existing outputs. The held-out evaluator performs no training, checkpoint selection or calibration. Do not use test results for retuning. Prepared-tile test scores do not establish whole-image seam performance or independence across geographic sources. DOTA scenes lack complete absolute-geolocation evidence; these internal splits are not official DOTA benchmark splits.

See LICENSE-NOTICES.txt, SOURCES.json and ontology.json. This research package is not commercially cleared.

Verified results

The selected semantic checkpoint is epoch 4 from a seven-epoch run on all 317 training tiles. Full fine-tuning took 1,488.63 seconds on CPU and stopped by patience. Selection used only 21 reserved semantic validation tiles. Fixed 20-tile quick mIoU improved from 0.1036 for adapted initialization to 0.5118. This comparison is validation evidence.

A single final held-out evaluation used frozen checkpoints and thresholds: 103 detection tiles and 42 semantic tiles. RESULTS.json contains the complete report and retained prediction hashes. These are component-level prepared-tile scores, not end-to-end large-image API benchmarks.

Measure	Held-out result
Detection AP50	0.6693
Detection mAP50–95	0.4008
Calibrated detection precision / recall / F1	0.8935 / 0.4223 / 0.5735
Semantic mIoU	0.4749
Building / road / water IoU	0.5970 / 0.5091 / 0.6250
Vegetation / agriculture IoU	0.6502 / 0.6108
Bare ground / developed area IoU	0 / 0.3320

Bare ground was not recognized. Vehicle operating recall was 0.2230 and bridge recall 0.2667. These are material limitations; the package is a research baseline, not a claim of reliable recognition across every supported category. Do not retune on these held-out results. Independent licensed external imagery, geographic certification and comparisons of alternative tile-fusion algorithms remain unverified.

Measured mean CPU prediction times were 0.111 seconds per detection tile and 0.092 seconds per semantic tile (four threads, native 1024). They include first-call setup/warmup, exclude checkpoint loading, and do not include whole-image stitching. Evaluation peak host RSS was approximately 595 MiB. No GPU was used.

Semantic ONNX passed parity on all 20 fixed quick tiles with pixel agreement 0.9999998569. Detector ONNX failed the strict class/count/polygon/confidence check on 32 quick tiles and was discarded. Its failure cause is not established. Use the supplied PyTorch detector.

Twenty-one focused unit tests passed across gates, semantic training, BatchNorm and inference. Actual corpus experiments, a standalone API smoke and export parity provided additional verification. The full historical test suite was not rerun. Six held-out comparison sheets were inspected: missed small vehicles, incomplete agricultural coverage and aquatic-vegetation/water boundary confusion remain visible.

Precision-first detection profiles

The original default remains available. Select a precision-oriented profile explicitly:

model = Model('model', detection_profile='detection-precision-first.json')
# Stricter alternative, with substantially lower recall:
# model = Model('model', detection_profile='detection-precision-strict.json')
result = model.predict('/absolute/path/to/rgb_image.tif')
print(result['detection_policy'])

Operating policy	Quick validation precision	Recall	TP / FP
Original F1 thresholds	0.9611	0.8058	469 / 19
Precision-first (selection target 0.99)	0.9821	0.7543	439 / 8
Strict (selection target 1.00)	0.9873	0.4021	234 / 3

Thresholds were fitted on 68 reserved validation tiles and checked on the same fixed 32 diagnostic quick tiles. No test data was read or recalibrated. The quick subset was inspected repeatedly during development, so these numbers are not independent proof of 99% precision. See PRECISION-RESULTS.json; the earlier RESULTS.json applies to the original default policy, not these profiles.

Neither profile achieved 99% quick precision. Both explicitly abstain on bridges: calibration has only seven positive bridge instances, insufficient for the minimum support screen. These targets remain false negatives in recall. The output lists abstained classes, and the API rejects a confidence override while a profile is active. All supported classes still exist in the original default mode.

A controlled head-only fine-tuning experiment retained frozen BN, LR1e-5 and the exact balanced 24-tile subset. It failed to improve mAP or recall at the precision-constrained operating points. Its weights were rejected; both shipped profiles use the unchanged pretrained detector. More epochs were not launched automatically.

Additional independent labeled evaluation imagery is needed to substantiate a 99% per-class claim, especially for bridges and the few-scene aircraft/tank categories. A larger training set may help, but its necessity is not established by these experiments. Prioritize diverse, correctly labeled bridges, small vehicles, tanks and hard negative backgrounds from the intended sensors/resolutions. Keep new evaluation scenes separate from training and preserve the original used test set as historical evidence.