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. For training and evaluation code, see the GitHub repository.

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:

pip install -U huggingface_hub

Download individual archives with the CLI:

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:

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.

<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.

<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:

git clone https://github.com/ymp5078/RulerNet.git
cd RulerNet
pip install -r requirements.txt

Use the final RulerNet checkpoint for inference:

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:

  --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:

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; they are not distributed as a separate archive.

ONNX inference

model.onnx is the CPU-ready export used by the interactive 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:

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:

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. 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. For commercial-use licensing inquiries, contact jwang@ist.psu.edu.