axis-line-detector

Fast, standalone detector for near-horizontal and near-vertical lines in images. Purpose-built for scanned documents, forms, and tables where lines fall within a few degrees of an axis.

Similar in spirit to OpenCV's FastLineDetector, but restricted to axis-aligned output and much simpler, faster and more robust.

Install

pip install axis-line-detector             # core detector (NumPy only)
pip install axis-line-detector[overlay]    # + Pillow for file bytes and overlay()

Building from source requires a C++17 compiler (GCC 7+, Clang 5+, MSVC 2017+).

Usage

from axis_line_detector import detect, overlay

with open("form.png", "rb") as f:
    data = f.read()

lines = detect(data, min_length=50)  # numpy.ndarray, shape (N, 4), float32
for x1, y1, x2, y2 in lines:
    print(f"({x1:.1f}, {y1:.1f}) -> ({x2:.1f}, {y2:.1f})")

# Overlay the detections onto the original image for quick visual inspection.
overlay(lines, data, "form_overlay.png")

Accepted inputs

Both detect and overlay accept the same set of image inputs. The Python wrapper normalizes them before calling the C++ core:

• bytes / bytearray / memoryview — raw encoded image file contents (PNG, JPEG, …), decoded with Pillow ([overlay] extra).
• str / os.PathLike — filesystem path to an image file (Pillow).
• 2-D numpy array — grayscale.
• 3-D, 1 or 2 channels — first channel used.
• 3-D, 3 or 4 channels — interpreted as RGB/RGBA and reduced with ITU-R BT.601 luminance. For BGR sources (OpenCV), reverse first: image[..., ::-1].
• uint16 — rescaled from [0, 65535] to [0, 255].
• float — assumed in [0.0, 1.0], scaled to [0, 255], clipped.
• bool — False→0, True→255.
• Other integer dtypes are clipped to [0, 255] and cast.

Non-contiguous inputs are copied automatically.

Visual inspection

overlay(lines, image, output_path, *, seed=0) renders each detected line into a PNG, and preserves the source image's colors. Pass the same image you gave to detect so the overlay lines up with the original pixels.

overlay and the file-bytes/path inputs to detect require Pillow; install with pip install axis-line-detector[overlay] or separately with pip install Pillow.

Behavior

Fixed characteristics of the detector (see src/axis_line_detector.cpp for full documentation and rationale):

• Only lines within 5 degrees of horizontal or vertical are returned.
• Up to 25,000 fragments per axis are retained (a forced cut-off to avoid spending too much time on weird images).
• min_length is required and must be a positive integer.

License

MIT. See LICENSE.