Update README.md

README.md

@@ -1,3 +1,202 @@
----
-license: cc-by-nc-sa-4.0
----
+---
+license: cc-by-nc-4.0
+tags:
+  - ruler-reading
+  - image-scale-estimation
+  - computer-vision
+  - onnx
+  - medical-imaging
+---
+
+# RulerNet
+
+RulerNet estimates image scale from a visible ruler by detecting centimeter
+marks and fitting them with a geometric progression. It is designed to remain
+robust when a ruler is rotated, viewed in perspective, or partially occluded.
+
+This repository accompanies **“RulerNet: Learning Perspective-Invariant Ruler
+Representations for Robust Image Scale Estimation,”** published in
+*Computerized Medical Imaging and Graphics*.
+
+Try the interactive CPU demo: [RulerNet-Demo](https://huggingface.co/spaces/ymp5078/RulerNet-Demo).
+For training and evaluation code, see the [GitHub repository](https://github.com/ymp5078/RulerNet).
+
+## Repository contents
+
+| Location | Contents | Use |
+| --- | --- | --- |
+| `data/AnyRuler.zip` | AnyRuler images and centimeter-mark annotations (998 MB) | Training and testing |
+| `data/Rulers2023_scale.zip` | Rulers2023 images and centimeter-mark annotations (2.46 GB) | Evaluation |
+| `weights/final_rulernet.zip` | Final RulerNet checkpoint (131 MB) | PyTorch inference, evaluation, or fine-tuning |
+| `weights/final_deepgp.zip` | DeepGP solver checkpoint (112 MB) | Optional faster geometric-progression solving |
+| `weights/pretrained_rulernet.zip` | Synthetic-data pretrained RulerNet checkpoint (158 MB) | Initialize training to reproduce the paper setup |
+| `model.onnx` | CPU-ready ONNX export (57.1 MB) | Lightweight deployment and inference |
+
+## Download files
+
+Install the Hugging Face Hub client:
+
+```bash
+pip install -U huggingface_hub
+```
+
+Download individual archives with the CLI:
+
+```bash
+hf download ymp5078/RulerNet data/AnyRuler.zip --local-dir .
+hf download ymp5078/RulerNet data/Rulers2023_scale.zip --local-dir .
+hf download ymp5078/RulerNet weights/final_rulernet.zip --local-dir .
+hf download ymp5078/RulerNet weights/final_deepgp.zip --local-dir .
+hf download ymp5078/RulerNet weights/pretrained_rulernet.zip --local-dir .
+hf download ymp5078/RulerNet model.onnx --local-dir .
+```
+
+Extract an archive before using it:
+
+```bash
+unzip data/AnyRuler.zip -d data/
+unzip weights/final_rulernet.zip -d weights/
+```
+
+## Datasets
+
+### AnyRuler
+
+`AnyRuler.zip` contains 1,416 annotated ruler images. Use it for training or
+for evaluating a model with centimeter-mark labels. After extraction, provide
+the extracted directory to the code repository with `--data-dir`.
+
+```text
+<data-dir>/
+├── ruler_image/    # input images
+└── cm_marks/       # matching JSON centimeter-mark annotations
+```
+
+### Rulers2023
+
+`Rulers2023_scale.zip` contains the Rulers2023 evaluation images together
+with centimeter-mark annotations. Use it with `--test-dataset ruler2023`.
+
+```text
+<data-dir>/
+├── real-test/images/       # evaluation images
+└── real-test-marks/        # JSON centimeter-mark annotations
+```
+
+## PyTorch checkpoints
+
+Clone the code repository and install its dependencies before using the
+checkpoints:
+
+```bash
+git clone https://github.com/ymp5078/RulerNet.git
+cd RulerNet
+pip install -r requirements.txt
+```
+
+Use the final RulerNet checkpoint for inference:
+
+```bash
+python inference.py \
+  --config configs/config_graphic_gen.yaml \
+  --checkpoint <path-to-final_rulernet>/checkpoints/epoch=199-step=20000.ckpt \
+  --img-size 768 768 \
+  --ruler-mode optimize \
+  --image-path <image-or-directory> \
+  --result-dir <output-directory>
+```
+
+Append the following option to the inference or evaluation command to use the
+optional learned DeepGP geometric-progression solver:
+
+```bash
+  --gp-solver-path <path-to-final_deepgp>/checkpoints/epoch=999-step=1200000.ckpt
+```
+
+To reproduce the pretraining initialization used in the paper, start training
+from the checkpoint in `pretrained_rulernet.zip`:
+
+```bash
+python main.py \
+  --config configs/config_pretrain.yaml \
+  --data-dir <anyruler-data-dir> \
+  --checkpoint <path-to-pretrained_rulernet>/checkpoints/epoch=79-step=128240.ckpt
+```
+
+The synthetic-ruler images used for pretraining are reproducible with
+[`sdxl_inference.py`](https://github.com/ymp5078/RulerNet/blob/main/sdxl_inference.py);
+they are not distributed as a separate archive.
+
+## ONNX inference
+
+`model.onnx` is the CPU-ready export used by the [interactive demo](https://huggingface.co/spaces/ymp5078/RulerNet-Demo).
+It expects a float32 tensor named `input` with shape **`(1, 3, 768, 768)`**:
+an RGB image scaled to `[0, 1]`, resized while preserving aspect ratio, and
+zero-padded to 768 × 768.
+
+Install the lightweight runtime:
+
+```bash
+pip install -U huggingface_hub onnxruntime numpy pillow
+```
+
+The following example downloads the model, prepares an image exactly as in the
+demo, and runs inference on CPU:
+
+```python
+import numpy as np
+import onnxruntime as ort
+from huggingface_hub import hf_hub_download
+from PIL import Image
+
+model_path = hf_hub_download(repo_id="ymp5078/RulerNet", filename="model.onnx")
+session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
+
+def preprocess(image_path):
+    image = np.asarray(Image.open(image_path).convert("RGB"), dtype=np.float32) / 255.0
+    height, width = image.shape[:2]
+    scale = min(768 / width, 768 / height)
+    new_width, new_height = int(width * scale), int(height * scale)
+
+    resized = Image.fromarray((image * 255).astype(np.uint8)).resize((new_width, new_height))
+    canvas = np.zeros((768, 768, 3), dtype=np.float32)
+    top = (768 - new_height) // 2
+    left = (768 - new_width) // 2
+    canvas[top:top + new_height, left:left + new_width] = np.asarray(resized) / 255.0
+
+    return np.transpose(canvas, (2, 0, 1))[None].astype(np.float32), (scale, top, left)
+
+input_tensor, transform = preprocess("ruler.jpg")
+init_point, dist, ratio, direction, points_info = session.run(
+    None, {"input": input_tensor}
+)
+
+print("initial point:", init_point[0])
+print("base distance:", dist[0])
+print("geometric-progression ratio:", ratio[0])
+print("ruler direction:", direction[0])
+print("point count and bounds:", points_info[0])
+```
+
+The five outputs are:
+
+| Output | Meaning |
+| --- | --- |
+| `init_point` | Predicted starting ruler-mark location in the 768 × 768 processed image |
+| `dist` | Base distance between generated marks |
+| `ratio` | Geometric-progression ratio between consecutive mark spacings |
+| `direction` | Unit direction vector along the ruler |
+| `points_info` | Number of generated points followed by `[min_x, min_y, max_x, max_y]` valid bounds |
+
+To reconstruct the full set of ruler-mark positions and calculate the median
+pixels-per-centimeter value, use the post-processing in the
+[demo implementation](https://huggingface.co/spaces/ymp5078/RulerNet-Demo/blob/main/app.py).
+The resulting coordinates are in the padded 768 × 768 image. To map a point
+`(x, y)` back to the original image, use `(x - left) / scale` and
+`(y - top) / scale`, where `scale`, `top`, and `left` are returned by
+`preprocess`.
+
+## License and commercial use
+
+This material is licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/).
+For commercial-use licensing inquiries, contact [jwang@ist.psu.edu](mailto:jwang@ist.psu.edu).