{"id":24951942,"url":"https://github.com/ocr-d/ocrd_olena","last_synced_at":"2025-07-20T06:04:19.678Z","repository":{"id":39997005,"uuid":"141301074","full_name":"OCR-D/ocrd_olena","owner":"OCR-D","description":"Binarize with Olena/scribo","archived":false,"fork":false,"pushed_at":"2025-05-01T19:00:26.000Z","size":212,"stargazers_count":7,"open_issues_count":2,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-01T20:19:53.700Z","etag":null,"topics":["ocr-d"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OCR-D.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-17T14:26:55.000Z","updated_at":"2025-05-01T19:00:29.000Z","dependencies_parsed_at":"2024-11-07T15:20:31.532Z","dependency_job_id":"37ecff46-9f51-4288-9494-1975c07e5e6b","html_url":"https://github.com/OCR-D/ocrd_olena","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/OCR-D/ocrd_olena","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCR-D%2Focrd_olena","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCR-D%2Focrd_olena/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCR-D%2Focrd_olena/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCR-D%2Focrd_olena/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OCR-D","download_url":"https://codeload.github.com/OCR-D/ocrd_olena/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCR-D%2Focrd_olena/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266076031,"owners_count":23872729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ocr-d"],"created_at":"2025-02-03T01:32:49.779Z","updated_at":"2025-07-20T06:04:19.647Z","avatar_url":"https://github.com/OCR-D.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ocrd_olena\n\n\u003e Binarize with Olena/scribo\n\n[![CircleCI](https://circleci.com/gh/OCR-D/ocrd_olena.svg?style=svg)](https://circleci.com/gh/OCR-D/ocrd_olena)\n[![Docker Automated build](https://img.shields.io/docker/automated/ocrd/core.svg)](https://hub.docker.com/r/ocrd/olena/tags/)\n\n## Requirements\n\n    make deps-ubuntu\n\n...will try to install the required packages on Ubuntu.\n\n## Installation\n\n    make build-olena\n\n...will download, patch and build Olena/scribo from source,\nand install its standalone CLI `scribo-cli` (see [below](#command-line-interface-scribo-cli))\nlocally (in `$VIRTUAL_ENV` or in `$PREFIX` if given).\n\n    make install\n\n...will run `build-olena`, if necessary, and install the Python\npackage `ocrd_olena` with the [OCR-D](https://ocr-d.de) [CLI](https://ocr-d.de/en/spec/cli)\n`ocrd-binarize-olena` (see [below](#ocr-d-processor-interface-ocrd-olena-binarize)).\n\n## Testing\n\n    make test\n\n...will clone the assets repository from Github, make a workspace copy, and run checksum tests\nfor binarization on them.\n\n## Usage\n\nThis package has the following user interfaces:\n\n### command line interface `scribo-cli`\n\nConverts images in any format.\n\n```\nUsage: scribo-cli COMMAND [ARGS]\n\nList of available COMMAND options:\n\n  Full Toolchains\n  ---------------\n\n\n   * On documents\n\n     doc-ppc\t       Common preprocessing before looking for text.\n\n     doc-ocr           Find and recognize text. Output: the actual text\n     \t\t       and its location.\n\n     doc-dia           Analyse the document structure and extract the\n     \t\t       text. Output: an XML file with region and text\n     \t\t       information.\n\n\n\n   * On pictures\n\n     pic-loc           Try to localize text if there's any.\n\n     pic-ocr           Localize and try to recognize text.\n\n\n\n  Tools\n  -----\n\n\n     * xml2doc\t       Convert the XML results of document toolchains\n       \t\t       into user documents (HTML, PDF...).\n\n\n  Algorithms\n  ----------\n\n\n   * Binarization\n\n     otsu              Otsu's (1979) global thresholding algorithm.\n\n     niblack           Niblack's (1985) local thresholding algorithm.\n\n     sauvola           Sauvola and Pietikainen's (2000) local/adpative algorithm.\n\n     kim               Kim's (2004) algorithm.\n\n     wolf              Wolf and Jolion's (2004) algorithm.\n\n     sauvola-ms        Lazzara's (2013) multi-scale Sauvola algorithm.\n\n     sauvola-ms-fg     Extract foreground objects and run multi-scale\n                       Sauvola's algorithm.\n\n     sauvola-ms-split  Run multi-scale Sauvola's algorithm on each color\n                       component and merge results.\n\n     singh             Singh's (2014) algorithm.\n\n\n  Other\n  -----\n\n     version           Show version and exit\n\n     help              Show this message and exit\n\n\nFor command arguments, see 'scribo-cli COMMAND --help' for more information\non each specific COMMAND.\n```\n\nFor example:\n\n    scribo-cli sauvola-ms path/to/input.tif path/to/output.png --enable-negate-output\n\nThis can also be used with the general-purpose image preprocessing OCR-D wrapper [ocrd-preprocess-image](https://github.com/bertsky/ocrd_wrap#ocr-d-processor-interface-ocrd-preprocess-image) to get the power of Olena's binarization to all structural levels of the PAGE segment hierarchy. (See [this parameter preset](https://github.com/bertsky/ocrd_wrap/blob/master/ocrd_wrap/param_scribo-cli-binarize-sauvola-ms-split.json) for an usage example.)\n\n### [OCR-D processor](https://ocr-d.de/en/spec/cli) interface `ocrd-olena-binarize`\n\nTo be used with [PageXML](https://github.com/PRImA-Research-Lab/PAGE-XML) documents in\nan [OCR-D](https://ocr-d.de) annotation workflow. Input could be any valid workspace\nwith source images available. Covers PAGE hierarchy levels `page`, `table`, `region` and\n`line`.\n\nUses either (the last) `AlternativeImage/@filename` (if any), or `Page/@imageFilename`\n(otherwise, cropping to `Border` if necessary). Adds an `AlternativeImage` with the\nresult of binarization for every segment.\n\n```\nUsage: ocrd-olena-binarize [worker|server] [OPTIONS]\n\n  popular binarization algorithms implemented by Olena/SCRIBO, wrapped for OCR-D\n\n  \u003e binarization with Scribo from Olena suite\n\n  \u003e For each page, open and deserialize PAGE input file (from existing\n  \u003e PAGE file in the input fileGrp, or generated from image file).\n  \u003e Retrieve its respective image  at the requested `level-of-operation`\n  \u003e (ignoring annotation that already added `binarized`).\n\n  \u003e Passes the image file to the Olena suite's scribo binarization\n  \u003e program for the selected algorithm `impl` and its parameters.\n\n  \u003e If binarization returns with a failure, skip that segment with an\n  \u003e approriate error message. Otherwise, put the resulting PNG image\n  \u003e file into the output fileGrp, and reference it in the METS using a\n  \u003e file ID with suffix ``.IMG-BIN``. Reference it as AlternativeImage\n  \u003e in the page, adding ``binarized`` to its @comments.\n\n  \u003e Produce a new PAGE output file by serialising the resulting\n  \u003e hierarchy.\n\nSubcommands:\n    worker      Start a processing worker rather than do local processing\n    server      Start a processor server rather than do local processing\n\nOptions for processing:\n  -m, --mets URL-PATH             URL or file path of METS to process [./mets.xml]\n  -w, --working-dir PATH          Working directory of local workspace [dirname(URL-PATH)]\n  -I, --input-file-grp USE        File group(s) used as input\n  -O, --output-file-grp USE       File group(s) used as output\n  -g, --page-id ID                Physical page ID(s) to process instead of full document []\n  --overwrite                     Remove existing output pages/images\n                                  (with \"--page-id\", remove only those).\n                                  Short-hand for OCRD_EXISTING_OUTPUT=OVERWRITE\n  --debug                         Abort on any errors with full stack trace.\n                                  Short-hand for OCRD_MISSING_OUTPUT=ABORT\n  --profile                       Enable profiling\n  --profile-file PROF-PATH        Write cProfile stats to PROF-PATH. Implies \"--profile\"\n  -p, --parameter JSON-PATH       Parameters, either verbatim JSON string\n                                  or JSON file path\n  -P, --param-override KEY VAL    Override a single JSON object key-value pair,\n                                  taking precedence over --parameter\n  -U, --mets-server-url URL       URL of a METS Server for parallel incremental access to METS\n                                  If URL starts with http:// start an HTTP server there,\n                                  otherwise URL is a path to an on-demand-created unix socket\n  -l, --log-level [OFF|ERROR|WARN|INFO|DEBUG|TRACE]\n                                  Override log level globally [INFO]\n  --log-filename LOG-PATH         File to redirect stderr logging to (overriding ocrd_logging.conf).\n\nOptions for information:\n  -C, --show-resource RESNAME     Dump the content of processor resource RESNAME\n  -L, --list-resources            List names of processor resources\n  -J, --dump-json                 Dump tool description as JSON\n  -D, --dump-module-dir           Show the 'module' resource location path for this processor\n  -h, --help                      Show this message\n  -V, --version                   Show version\n\nParameters:\n   \"level-of-operation\" [string - \"page\"]\n    PAGE XML segment hierarchy level to annotate images for\n    Possible values: [\"page\", \"table\", \"region\", \"line\"]\n   \"impl\" [string - \"sauvola-ms-split\"]\n    The name of the actual binarization algorithm\n    Possible values: [\"sauvola\", \"sauvola-ms\", \"sauvola-ms-fg\", \"sauvola-\n    ms-split\", \"kim\", \"wolf\", \"niblack\", \"singh\", \"otsu\"]\n   \"k\" [number - 0.34]\n    Sauvola's formulae parameter (foreground weight decreases with k);\n    for Multiscale, multiplied to yield default 0.2/0.3/0.5; for Singh,\n    multiplied to yield default 0.06; for Niblack, multiplied to yield\n    default -0.2; for Wolf/Kim, used directly; for Otsu, does not apply\n   \"win-size\" [number - 0]\n    The (odd) window size in pixels; when zero (default), set to DPI (or\n    301); for Otsu, does not apply\n   \"dpi\" [number - 0]\n    pixel density in dots per inch (overrides any meta-data in the\n    images); disabled when zero\n```\n\n## License\n\nCopyright 2018-2023 Project OCR-D\n\nocrd_olena is released under the GNU General Public Licence.  See the file\n``LICENSE`` (at the root of the source tree) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focr-d%2Focrd_olena","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Focr-d%2Focrd_olena","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focr-d%2Focrd_olena/lists"}