Clarify PP-DocLayout V3 usage

Document native MLX loading, output coordinates, and validation scope.

README.md

@@ -6,27 +6,79 @@ tags:
 - mlx
 - object-detection
 - document-layout
+- reading-order
 library_name: mlx-vlm
+pipeline_tag: object-detection
+license: apache-2.0
+base_model: PaddlePaddle/PP-DocLayoutV3_safetensors
 ---
 
-# pp-doclayout-v3-mlx
+# PP-DocLayout V3 (MLX)
 
-MLX port of [PaddlePaddle/PP-DocLayoutV3_safetensors](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors):
-RT-DETR-style document layout detector, 25 classes plus a reading-order
-head (33M params, float32).
+MLX conversion of [PaddlePaddle/PP-DocLayoutV3_safetensors](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors)
+for document-layout detection on Apple Silicon. It predicts page regions,
+class labels, and reading order; it does not transcribe text.
+
+- **Architecture:** HGNetV2-L backbone, hybrid encoder, and deformable decoder
+  with a reading-order head.
+- **Classes:** 25 prediction classes from the stock checkpoint.
+- **Weights:** about 33M parameters, float32, 133 MB, not quantized.
+
+## Usage
+
+Use an [mlx-vlm](https://github.com/Blaizzy/mlx-vlm) checkout that includes
+`pp_doclayout_v3` support. From that checkout:
+
+```sh
+python -m pip install -e .
+```
+
+Replace `page.png` with a document image:
 
 ```python
-from mlx_vlm.utils import load_model
+from mlx_vlm.utils import get_model_path, load_model
 
-model = load_model("HashNuke/pp-doclayout-v3-mlx")
+model = load_model(get_model_path("HashNuke/pp-doclayout-v3-mlx"))
 model.eval()
-print(model.detect("page.png", conf=0.5))
+records = model.detect("page.png", conf=0.5)
+for record in sorted(records, key=lambda item: item["reading_order"]):
+    print(record)
 ```
 
-Also usable as the layout backend for Falcon-OCR style pipelines, and
-the architecture twin of the 37-class IndicDocLayout fine-tune
-(`HashNuke/indic-ocr-mlx` `weights/layout`).
+`get_model_path` downloads the checkpoint and returns a local path for
+`load_model`. `detect` accepts an image path or a PIL image.
+
+## Output format
+
+Each detection contains:
+
+- `bbox`: `[y0, x0, y1, x1]`, normalized to 0–1000 and rounded to one decimal.
+- `label`: the checkpoint's class name.
+- `reading_order`: a one-based rank among retained detections.
+- `score`: confidence rounded to three decimals.
+
+The returned list is in query order; sort by `reading_order` to consume it in
+document order. This MLX interface returns rectangular boxes, not polygons or
+segmentation masks.
+
+The default inference recipe resizes RGB images to 1024×1024 and scales pixels
+to [0, 1]. This matches IndicDocLayout's preprocessing and differs from the
+stock Transformers processor's defaults. The mask-feature branch is retained
+for mask-enhanced query initialization; training-only denoising weights are omitted.
+
+## Validation
+
+At `conf=0.5` with the same preprocessing and reading-order decoding, output
+records matched fresh PyTorch reference runs on the English paper and
+calendar/table samples in mlx-vlm (`examples/images/paper.png` and
+`examples/images/demo_pdf1_page1.png`). Labels, reading order, and rounded
+boxes/scores matched. This is sample-level output parity, not bitwise equality
+of raw tensors or a detection-accuracy benchmark.
+
+The 37-class IndicDocLayout fine-tune is available separately as the layout
+stage of [IndicOCR (MLX)](https://huggingface.co/HashNuke/indic-ocr-mlx).
+
+## License
 
-Original weights: Apache-2.0. Port code:
-`mlx_vlm/models/pp_doclayout_v3` in mlx-vlm. Converted with
-`python -m mlx_vlm.models.pp_doclayout_v3.convert --dtype float32`.
+The [upstream weights](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors)
+are licensed under Apache-2.0. This conversion does not change that license.