GeoOCR

GeoOCR is a Python library for automating OCR on historical archive images and extracting geospatial data. It provides:

• ArchiveImage: image preprocessing, splitting and OCR.
• ArchiveCollection: batch operations on collections of images.
• ArchiveGeolocator: fuzzy-match CSV addresses against a GeoJSON reference to geolocate.
• GeoExporter: export results to CSV or GeoJSON.

We recommend using it with Google Colab or Jupyter Notebook.

Note: This project was developed for a specific university research project and is not guaranteed to be maintained.

Installation

pip install geocr

Or install from source:

git clone https://github.com/joshuavachon25/geocr-py.git
cd geocr
pip install .

Quickstart

Normal usage involves creating a collection, batch-processing what you can, then applying specific pipelines to individual items. After that, you perform OCR, extract and correct the data, and generate a CSV file that can be used with the Geolocator along with GIS data.

from geocr.archive_image import ArchiveImage
from geocr.archive_collection import ArchiveCollection
from geocr.archive_geolocator import ArchiveGeolocator
from geocr.geo_exporter import GeoExporter
from shapely.geometry import Point
import cv2

# 1. Process an image
img = ArchiveImage(cv2.imread("/path/to/image.png"), name="example")
img.sharpen().binarize().ocr(language='fra', config='--psm 3')
print(img.ocr_text)

# 2. Batch process a folder 
col = ArchiveCollection("/path/to/images")
col.sharpen().binarize().ocr()
all_text = col.get_ocr_text()

# 3. Geocode addresses
locator = ArchiveGeolocator("rues.geojson", default_point=Point(0,0))
gdf = locator.geocode_csv(
    csv_path="adresses.csv",
    csv_fields=["No","Adresse"],
    ref_fields=["adresses"],
    similarity_threshold=85
)

# 4. Export results
GeoExporter.to_csv(gdf, "results.csv")
GeoExporter.to_geojson(gdf, "results.geojson")

API Reference

ArchiveImage

ArchiveImage(image: np.ndarray, name: str)

Constructor: wraps an OpenCV image.

ArchiveCollection

ArchiveCollection(input_path: str, is_natural_sort=True, split_template=None, split_orientation='vertical')

Constructor: loads images from folder.

ArchiveGeolocator

ArchiveGeolocator(reference_geojson_path: str, default_point: Point = Point(0,0))

Constructor: loads GeoJSON reference.

gdf = geolocator.geocode_csv(
    csv_path: str = None,
    gdf: GeoDataFrame = None,
    csv_fields: list[str] = ['Adresse'],
    ref_fields: list[str] = ['nom_voie'],
    output_geometry: str = 'geometry',
    match_label: str = 'matched_ref',
    score_label: str = 'match_score',
    similarity_threshold: float = 80,
    sep: str = ';',
    method: string = "difflib" #difflib or rapidfuzz
) -> GeoDataFrame

• If gdf provided, reuses it; otherwise loads CSV.
• Only geocodes rows where geometry is missing or equals default_point.
• Returns GeoDataFrame with original columns + output_geometry, match_label, score_label.

GeoExporter

GeoExporter.to_csv(gdf: GeoDataFrame, path: str, sep: str = ';')

Export attribute table to CSV (drops geometry).

GeoExporter.to_geojson(gdf: GeoDataFrame, path: str)

Export full GeoDataFrame to GeoJSON.

License

This project is licensed under the MIT License. See the LICENSE file for details.