Skip to main content

An image binarization library focussing on local adaptive thresholding

Project description

DoxaPy

Introduction

DoxaPy is an image binarization library focussing on local adaptive thresholding algorithms. In English, this means that it has the ability to turn a color or gray scale image into a black and white image.

Algorithms

  • Otsu - "A threshold selection method from gray-level histograms", 1979.
  • Bernsen - "Dynamic thresholding of gray-level images", 1986.
  • Niblack - "An Introduction to Digital Image Processing", 1986.
  • Sauvola - "Adaptive document image binarization", 1999.
  • Wolf - "Extraction and Recognition of Artificial Text in Multimedia Documents", 2003.
  • Gatos - "Adaptive degraded document image binarization", 2005. (Partial)
  • NICK - "Comparison of Niblack inspired Binarization methods for ancient documents", 2009.
  • Su - "Binarization of Historical Document Images Using the Local Maximum and Minimum", 2010.
  • T.R. Singh - "A New local Adaptive Thresholding Technique in Binarization", 2011.
  • Bataineh - "An adaptive local binarization method for document images based on a novel thresholding method and dynamic windows", 2011. (unreproducible)
  • ISauvola - "ISauvola: Improved Sauvola’s Algorithm for Document Image Binarization", 2016.
  • WAN - "Binarization of Document Image Using Optimum Threshold Modification", 2018.

Optimizations

  • Shafait - "Efficient Implementation of Local Adaptive Thresholding Techniques Using Integral Images", 2008.
  • Petty - An algorithm for efficiently calculating the min and max of a local window. Unpublished, 2019.
  • Chan - "Memory-efficient and fast implementation of local adaptive binarization methods", 2019.

Performance Metrics

  • Overall Accuracy
  • F-Measure
  • Peak Signal-To-Noise Ratio (PSNR)
  • Negative Rate Metric (NRM)
  • Matthews Correlation Coefficient (MCC)
  • Distance-Reciprocal Distortion Measure (DRDM) - "An Objective Distortion Measure for Binary Document Images Based on Human Visual Perception", 2002.

Overview

DoxaPy uses the Δoxa Binarization Framework for quickly processing python Image files.

Example

This short demo uses DoxaPy to read in a color image, converts it to binary, and then compares it to a Ground Truth image in order to calculate performance.

from PIL import Image
import numpy as np
import doxapy

def read_image(file):
    return np.array(Image.open(file).convert('L'))


# Read our target image and setup an output image buffer
grayscale_image = read_image("2JohnC1V3.png")
binary_image = np.empty(grayscale_image.shape, grayscale_image.dtype)

# Pick an algorithm from the DoxaPy library and convert the image to binary
sauvola = doxapy.Binarization(doxapy.Binarization.Algorithms.SAUVOLA)
sauvola.initialize(grayscale_image)
sauvola.to_binary(binary_image, {"window": 75, "k": 0.2})

# Calculate the binarization performance using a Ground Truth image
groundtruth_image = read_image("2JohnC1V3-GroundTruth.png")
performance = doxapy.calculate_performance(groundtruth_image, binary_image)
print(performance)

# Display our resulting image
Image.fromarray(binary_image).show()

Alternative Calls

DoxaPy can very efficiently reuse the same memory buffer for converting a grayscale image to binary. Unless you are constantly changing algorithm parameters for the same image, it is recommended that you call this method.

# Transforms the grayscale image buffer into binary with a single call
doxapy.Binarization.update_to_binary(doxapy.Binarization.Algorithms.NICK, grayscale_image)

Building with Pybind11

Release Build - Requires: NumPy, Pybind11

clone https://github.com/brandonmpetty/Doxa
cd Doxa/Bindings/Python
python copy-cpp-files.py
python setup.py install

License

CC0 - Brandon M. Petty, 2021

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.

View Online

"Freely you have received; freely give." - Matt 10:8

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

doxapy-0.9.2.tar.gz (35.7 kB view hashes)

Uploaded Source

Built Distributions

doxapy-0.9.2-pp39-pypy39_pp73-win_amd64.whl (115.7 kB view hashes)

Uploaded PyPy Windows x86-64

doxapy-0.9.2-pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (165.9 kB view hashes)

Uploaded PyPy manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-pp39-pypy39_pp73-macosx_10_14_x86_64.whl (145.6 kB view hashes)

Uploaded PyPy macOS 10.14+ x86-64

doxapy-0.9.2-pp38-pypy38_pp73-win_amd64.whl (115.8 kB view hashes)

Uploaded PyPy Windows x86-64

doxapy-0.9.2-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (167.1 kB view hashes)

Uploaded PyPy manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-pp38-pypy38_pp73-macosx_10_14_x86_64.whl (145.6 kB view hashes)

Uploaded PyPy macOS 10.14+ x86-64

doxapy-0.9.2-pp37-pypy37_pp73-win_amd64.whl (115.5 kB view hashes)

Uploaded PyPy Windows x86-64

doxapy-0.9.2-pp37-pypy37_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (167.6 kB view hashes)

Uploaded PyPy manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-pp37-pypy37_pp73-macosx_10_14_x86_64.whl (145.2 kB view hashes)

Uploaded PyPy macOS 10.14+ x86-64

doxapy-0.9.2-cp311-cp311-win_amd64.whl (116.7 kB view hashes)

Uploaded CPython 3.11 Windows x86-64

doxapy-0.9.2-cp311-cp311-musllinux_1_1_x86_64.whl (689.7 kB view hashes)

Uploaded CPython 3.11 musllinux: musl 1.1+ x86-64

doxapy-0.9.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (175.4 kB view hashes)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-cp311-cp311-macosx_10_14_x86_64.whl (138.1 kB view hashes)

Uploaded CPython 3.11 macOS 10.14+ x86-64

doxapy-0.9.2-cp310-cp310-win_amd64.whl (116.6 kB view hashes)

Uploaded CPython 3.10 Windows x86-64

doxapy-0.9.2-cp310-cp310-musllinux_1_1_x86_64.whl (689.7 kB view hashes)

Uploaded CPython 3.10 musllinux: musl 1.1+ x86-64

doxapy-0.9.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (175.4 kB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-cp310-cp310-macosx_10_14_x86_64.whl (138.2 kB view hashes)

Uploaded CPython 3.10 macOS 10.14+ x86-64

doxapy-0.9.2-cp39-cp39-win_amd64.whl (115.7 kB view hashes)

Uploaded CPython 3.9 Windows x86-64

doxapy-0.9.2-cp39-cp39-musllinux_1_1_x86_64.whl (690.1 kB view hashes)

Uploaded CPython 3.9 musllinux: musl 1.1+ x86-64

doxapy-0.9.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (175.3 kB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-cp39-cp39-macosx_10_14_x86_64.whl (138.3 kB view hashes)

Uploaded CPython 3.9 macOS 10.14+ x86-64

doxapy-0.9.2-cp38-cp38-win_amd64.whl (116.6 kB view hashes)

Uploaded CPython 3.8 Windows x86-64

doxapy-0.9.2-cp38-cp38-musllinux_1_1_x86_64.whl (689.7 kB view hashes)

Uploaded CPython 3.8 musllinux: musl 1.1+ x86-64

doxapy-0.9.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (175.3 kB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-cp38-cp38-macosx_10_14_x86_64.whl (138.1 kB view hashes)

Uploaded CPython 3.8 macOS 10.14+ x86-64

doxapy-0.9.2-cp37-cp37m-win_amd64.whl (117.2 kB view hashes)

Uploaded CPython 3.7m Windows x86-64

doxapy-0.9.2-cp37-cp37m-musllinux_1_1_x86_64.whl (693.3 kB view hashes)

Uploaded CPython 3.7m musllinux: musl 1.1+ x86-64

doxapy-0.9.2-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (176.8 kB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-cp37-cp37m-macosx_10_14_x86_64.whl (136.1 kB view hashes)

Uploaded CPython 3.7m macOS 10.14+ x86-64

doxapy-0.9.2-cp36-cp36m-win_amd64.whl (117.7 kB view hashes)

Uploaded CPython 3.6m Windows x86-64

doxapy-0.9.2-cp36-cp36m-musllinux_1_1_x86_64.whl (693.7 kB view hashes)

Uploaded CPython 3.6m musllinux: musl 1.1+ x86-64

doxapy-0.9.2-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (177.1 kB view hashes)

Uploaded CPython 3.6m manylinux: glibc 2.17+ x86-64

doxapy-0.9.2-cp36-cp36m-macosx_10_14_x86_64.whl (136.2 kB view hashes)

Uploaded CPython 3.6m macOS 10.14+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page