Store inference weights as safetensors with a strict direct loader

LICENSING.md

@@ -2,8 +2,8 @@
 
 | Artifact | License |
 | --- | --- |
-| `v3.pth` model weights | Apache-2.0; full text in `LICENSE`, with upstream attribution in `NOTICE`. |
-| `predict.py` and `inference_engine.py` | AGPL-3.0-only; full text in `LICENSE-CODE-AGPL-3.0.txt`. These files are the complete release program source. |
+| `model.safetensors` model weights | Apache-2.0; full text in `LICENSE`, with upstream attribution in `NOTICE`. |
+| `predict.py`, `inference_engine.py`, and `model_loader.py` | AGPL-3.0-only; full text in `LICENSE-CODE-AGPL-3.0.txt`. These files are the complete release program source. |
 | Release documentation | Apache-2.0, except third-party notices and license texts, which retain their terms. |
 | Public dataset material | Not redistributed. Uploader-listed CC BY 4.0; credits/modification notes are retained in README and NOTICE, with license text in `LICENSE-CC-BY-4.0.txt`. |
 | Separately installed dependencies | Their own licenses and notices. No dependency binaries or environments are bundled. |
@@ -22,7 +22,7 @@ AGPL permits commercial activity when its terms are met. A proprietary integrati
 
 ## Source and installation
 
-Both Python source files, pinned requirements, full license texts and installation/inference commands are included in this package. `requirements-lock-macos-py313.txt` records the tested dependency resolution. No private local module, training records or drawings are needed to run the CLI. `SHA256SUMS` verifies the package files.
+All three Python source files, pinned requirements, full license texts and installation/inference commands are included in this package. `requirements-lock-macos-py313.txt` records the tested dependency resolution. No private local module, training records or drawings are needed to run the CLI. `SHA256SUMS` verifies the package files.
 
 Unmodified dependencies are obtained from their publishers. Exact releases include [PyMuPDF 2.0](https://pypi.org/project/PyMuPDF/2.0/#files) ([source](https://github.com/pymupdf/PyMuPDF), [MuPDF](https://mupdf.com/releases)) and [RF-DETR 1.11.2](https://pypi.org/project/rfdetr/1.11.2/#files) ([source](https://github.com/roboflow/rf-detr)). Preserve matching source/notices when conveying dependencies. This repository is not a binary-distribution compliance bundle.
 

NOTICE

@@ -10,7 +10,9 @@ https://storage.googleapis.com/rfdetr/small_coco/checkpoint_best_regular.pth
 https://roboflow.com/licensing
 
 Changes: the native base was fine-tuned for door openings. The release checkpoint
-retains inference tensors while omitting training records/identifying metadata.
+retains inference tensor names, shapes, dtypes and values in safetensors while
+omitting training records/identifying metadata. Packaging conversion does not
+retrain the model or change its inference preprocessing.
 The release CLI adapts the existing inference implementation for portable use.
 RF-DETR acknowledges LW-DETR, DINOv2 and Deformable DETR in its distribution.
 No standalone upstream NOTICE was present in the installed RF-DETR distribution;

README.md

@@ -21,7 +21,7 @@ Fine-tuned using public floor-plan datasets and additional architectural drawing
 
 One opening counts as one item; double doors should count as one opening. The single foreground class is `door` (ID 0). Windows and cabinets are outside the intended class. Predictions require human review, including areas where no box was proposed. Counts are preliminary and do not automatically identify unique physical openings across repeated drawings.
 
-**License scope:** `v3.pth` model weights are Apache-2.0. The supplied Python runner, including PDF functionality, is AGPL-3.0-only. See [LICENSING.md](LICENSING.md) and [NOTICE](NOTICE).
+**License scope:** `model.safetensors` model weights are Apache-2.0. The supplied Python runner, including PDF functionality, is AGPL-3.0-only. See [LICENSING.md](LICENSING.md) and [NOTICE](NOTICE).
 
 ## Install
 
@@ -34,7 +34,7 @@ python -m pip install -r requirements.txt
 python -m pip check
 ```
 
-`requirements-lock-macos-py313.txt` provides the complete tested dependency resolution for that platform. Training and web-server extras are not required. This is a native `rfdetr==1.11.2` PyTorch checkpoint, not a Transformers `from_pretrained` bundle.
+`requirements-lock-macos-py313.txt` provides the complete tested dependency resolution for that platform. Training and web-server extras are not required. The weights are stored in safetensors and loaded directly by `model_loader.py` with the pinned `rfdetr==1.11.2` implementation. No `.pth` file, pickle loading, conversion back to pickle, or base-weight download is required at runtime. This package does not implement or claim Transformers `pipeline()` / `from_pretrained()` compatibility.
 
 ## Predict
 
@@ -51,7 +51,7 @@ python predict.py --input plan.pdf --pages 1 --output results-pdf --device cpu
 python predict.py --input plan.pdf --pages 2,4-6 --output results-selected --device cpu
 ```
 
-Each output directory must be new. `v3.pth` is selected relative to the script by default. Apple Silicon users can use `--device mps`. `--device cuda` requires a compatible PyTorch/CUDA installation; CUDA and other operating systems have not been validated for this release.
+Each output directory must be new. `model.safetensors` is selected relative to the script by default. Apple Silicon users can use `--device mps`. `--device cuda` requires a compatible PyTorch/CUDA installation; CUDA and other operating systems have not been validated for this release.
 
 Optional drawing-area crop and render preview:
 
@@ -63,7 +63,21 @@ python predict.py --help
 
 ROI bounds are left/top/right/bottom percentages. Image loading applies EXIF orientation, composites transparency onto white, and converts to RGB. PDFs are rendered in RGB at **150 DPI** by default, with a 40-million-pixel page limit.
 
-Inference uses **768×768** white-padded tiles with **384-pixel stride**, model resolution **512×512**, confidence threshold **0.3**, tile-boundary rechecks, and final greedy NMS with IoU **0.5**. The model constructor is `RFDETRSmall(pretrain_weights=..., num_classes=1, resolution=512, device=...)`. The existing box/score handling is preserved without adding a class filter. Override settings with `--dpi`, `--threshold`, `--nms-iou`, or `--checkpoint`; changing settings can change predictions.
+Inference uses **768×768** white-padded tiles with **384-pixel stride**, model resolution **512×512**, confidence threshold **0.3**, tile-boundary rechecks, and final greedy NMS with IoU **0.5**. The direct loader constructs `RFDETRSmall(pretrain_weights=None, num_classes=1, resolution=512, device=...)`, strictly loads the included safetensors state, restores class names, and uses the existing RF-DETR prediction facade. The existing box/score handling is preserved without adding a class filter. Override settings with `--dpi`, `--threshold`, `--nms-iou`, `--checkpoint` (a safetensors file), or `--model-config` (defaults beside weights); changing settings can change predictions.
+
+## Direct loader
+
+`model_loader.py` reads `model_config.json` and `model.safetensors` directly. The minimal config contains only the pinned RF-DETR version, Small variant, resolution, foreground class count and class mapping. Architecture defaults are fixed by `rfdetr==1.11.2`: a windowed DINOv2 Small encoder, three decoder layers, patch size 16, positional grid 32 and 300 queries / 13 groups. The loader rejects unsupported config/version, missing or unexpected weight keys, and incompatible shapes or dtypes. It uses strict state loading and confirms the loaded tensors match the file. The model runs without optimization, quantization, or precision conversion.
+
+The image commands above use this loader together with the unchanged image preprocessing, tiling, boundary rechecks and NMS in `inference_engine.py`. A minimal Python loading example is:
+
+```python
+from model_loader import load_model
+
+model = load_model(device="cpu")  # model.safetensors + model_config.json beside loader
+```
+
+Use `predict.py` for image/PDF prediction with the complete preprocessing shown above. Initializing the model without pretrained weights creates its architecture locally; every required state tensor is then supplied by the strict safetensors load. The file preserves the original tensor names, shapes, dtypes and values, including its empty boolean buffer. No keys are dropped to deduplicate shared storage.
 
 ## Outputs and limitations
 

SHA256SUMS

@@ -1,11 +1,13 @@
 8cabf52c61130fc97a7e5da5e3685ccf44841c0c53d6f881189369b136603cca  LICENSE
 9ba9550ad48438d0836ddab3da480b3b69ffa0aac7b7878b5a0039e7ab429411  LICENSE-CC-BY-4.0.txt
 57c8ff33c9c0cfc3ef00e650a1cc910d7ee479a8bc509f6c9209a7c2a11399d6  LICENSE-CODE-AGPL-3.0.txt
-f40718c0158ad8eaff3ef127571c151035966b44b5f70ddf4b3f4adddd45430d  LICENSING.md
-0dfdf3ee9cdbe6061163b5d0812329f1d0a133014095611fdcb0558be7a016bb  NOTICE
-0b55369b068e12ed6157294c3923e801c5081593f81899e6ff1cbc808ff4bcfd  README.md
-90becba403ec439e4825c15f5aa390464f1b174169301cd652175be51a79c63d  inference_engine.py
+39c8f97aa86f61a2d47d13cd1aac0667333fff03339421fefede6bb437be739a  LICENSING.md
+e254f895fbdbe26efea3aa2a9d07f0c19d2e6c0fd4b5ec09367cd52816ee88fe  NOTICE
+3457211166e298fbdbd7f790727a292786d7741c60776f9373ce7836264727cb  README.md
+01a1c9a923de14a8af1b36078121328182db7208ae76e9664f742b6f0a22725c  inference_engine.py
+aca8b59ff9c6f144a1ca284f689683e9ed7cd951555832cfc09c10e5ae93bd0d  model.safetensors
+4b143322ca27af276eb497a959009b14729accf70d2bfaee98e751a8073b9443  model_config.json
+ec26695f9ba3bc72d4b9bd48414183af3ef5ccc6f03c473c26f12844cc25b308  model_loader.py
 e904d946b83504016bf6b83a452b8959212e07245c58424b5fccdeac7daffafb  predict.py
 6828f00d1c7922c5f3b7af01708e65b19581f38a0929b27d7e521b9ff66ab77b  requirements-lock-macos-py313.txt
-a212fdb899ea5fbea8a0da96a0c3618f7ca693f89ab59117c7436c3c94ecf618  requirements.txt
-518e463dfc63c4ebcac82b7719f82a105c2e8c2e3461326933996cbc8becd0b3  v3.pth
+5f29cba77ad563b6fe076b2364afc921894bad2bad0617529c9f85e71746cd26  requirements.txt

inference_engine.py

@@ -198,7 +198,8 @@ def main():
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument('--input', required=True, type=Path, help='PDF or one PNG/JPEG image.')
     parser.add_argument('--pages', help='Required for PDFs: 1-based page numbers, e.g. 5 or 5,7-9.')
-    parser.add_argument('--checkpoint', type=Path, default=Path(__file__).resolve().parent / 'v3.pth')
+    parser.add_argument('--checkpoint', type=Path, default=Path(__file__).resolve().parent / 'model.safetensors')
+    parser.add_argument('--model-config', type=Path, help='Architecture JSON; defaults beside weights.')
     parser.add_argument('--output', type=Path, help='New output folder; defaults to a timestamped outputs/ folder.')
     parser.add_argument('--dpi', type=int, default=150, help='PDF rendering DPI. Default: 150, matching training preparation.')
     parser.add_argument('--threshold', type=float, default=.3)
@@ -257,14 +258,13 @@ def main():
         if installed != '1.11.2':
             parser.error(f'This script requires RF-DETR 1.11.2; found {installed}.')
         import torch
-        from rfdetr import RFDETRSmall
+        from model_loader import load_model
         if args.device == 'mps' and not torch.backends.mps.is_available():
             parser.error('MPS unavailable; use the Mac environment or pass --device cpu.')
         if args.device == 'cuda' and not torch.cuda.is_available():
             parser.error('CUDA unavailable.')
-        print('Loading v3 door checkpoint...', flush=True)
-        model = RFDETRSmall(pretrain_weights=str(args.checkpoint.resolve()), num_classes=1,
-                           resolution=512, device=args.device)
+        print('Loading safetensors door weights...', flush=True)
+        model = load_model(args.checkpoint, args.model_config, device=args.device)
     output.mkdir(parents=True)
     report = dict(input=args.input.name, checkpoint=None if args.preview_only else args.checkpoint.name,
                   status='running', preview_only=args.preview_only, threshold=args.threshold, nms_iou=args.nms_iou,

v3.pth → model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:518e463dfc63c4ebcac82b7719f82a105c2e8c2e3461326933996cbc8becd0b3
-size 127326537
+oid sha256:aca8b59ff9c6f144a1ca284f689683e9ed7cd951555832cfc09c10e5ae93bd0d
+size 127223664

model_config.json

@@ -0,0 +1,9 @@
+{
+  "variant": "RFDETRSmall",
+  "rfdetr_version": "1.11.2",
+  "resolution": 512,
+  "num_classes": 1,
+  "id2label": {
+    "0": "door"
+  }
+}

model_loader.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Safetensors loading added 2026-10-28; inference preprocessing is unchanged.
+"""Strict, direct safetensors loader for this pinned RF-DETR Small release."""
+from importlib.metadata import version
+import json
+from pathlib import Path
+import warnings
+
+import torch
+from safetensors.torch import load_file
+
+HERE = Path(__file__).resolve().parent
+
+
+def load_model(weights_path=None, config_path=None, device='cpu'):
+    """Rebuild Small, load every tensor strictly, and return its RF-DETR facade.
+
+    No checkpoint deserialization, temporary pickle, pretrained download, dtype
+    conversion, or inference optimization is used. The CLI supplies the existing
+    RGB preparation, tiling, boundary rechecks and NMS via inference_engine.py.
+    """
+    weights_path = Path(weights_path) if weights_path is not None else HERE / 'model.safetensors'
+    config_path = Path(config_path) if config_path is not None else weights_path.parent / 'model_config.json'
+    if weights_path.suffix != '.safetensors':
+        raise ValueError('Use a .safetensors weights file.')
+    config = json.loads(config_path.read_text())
+    expected_config = {
+        'variant': 'RFDETRSmall', 'rfdetr_version': '1.11.2',
+        'resolution': 512, 'num_classes': 1, 'id2label': {'0': 'door'},
+    }
+    if config != expected_config:
+        raise ValueError('model_config.json does not describe this RF-DETR Small release.')
+    if version('rfdetr') != config['rfdetr_version']:
+        raise RuntimeError('Install the pinned rfdetr==1.11.2 inference dependencies.')
+    if device not in ('cpu', 'mps', 'cuda'):
+        raise ValueError('Choose cpu, mps or cuda.')
+    if device == 'mps' and not torch.backends.mps.is_available():
+        raise RuntimeError('MPS unavailable; use --device cpu.')
+    if device == 'cuda' and not torch.cuda.is_available():
+        raise RuntimeError('CUDA unavailable; use --device cpu.')
+
+    from rfdetr import RFDETRSmall
+    from rfdetr.config import PretrainWeightsCompatibilityWarning
+
+    # The pinned Small constructor uses bundled backbone configuration. Patch 16
+    # and positional grid 32 create the backbone locally, without DINOv2 weights.
+    # Its expected "initialised from scratch" warning is superseded by the strict
+    # complete-state load below; no randomly initialized weights remain in use.
+    with warnings.catch_warnings():
+        warnings.simplefilter('ignore', PretrainWeightsCompatibilityWarning)
+        model = RFDETRSmall(pretrain_weights=None, num_classes=config['num_classes'],
+                           resolution=config['resolution'], device=device)
+    module = model.model.model
+    state = load_file(str(weights_path), device='cpu')
+    expected = module.state_dict()
+    missing = sorted(expected.keys() - state.keys())
+    unexpected = sorted(state.keys() - expected.keys())
+    if missing or unexpected:
+        raise RuntimeError(f'Weight key mismatch: missing={missing}, unexpected={unexpected}')
+    for name, tensor in state.items():
+        if tensor.shape != expected[name].shape or tensor.dtype != expected[name].dtype:
+            raise RuntimeError(f'Weight shape/dtype mismatch: {name}')
+    module.load_state_dict(state, strict=True)
+    loaded_state = module.state_dict()
+    if not all(torch.equal(tensor, loaded_state[name]) for name, tensor in state.items()):
+        raise RuntimeError('Loaded model tensors do not exactly match the safetensors file.')
+    module.eval()
+    model.model.class_names = [config['id2label'][str(i)] for i in range(config['num_classes'])]
+    model.model.args.class_names = model.model.class_names
+    return model

requirements.txt

@@ -8,3 +8,4 @@ pymupdf==2.0
 supervision==0.30.8
 transformers==5.19.0
 huggingface_hub==1.33.0
+safetensors==0.8.0