Merge pull request #11 from bertsky/respect-pageid

expose input and output options
OCR-D · Dec 27, 2019 · 759fd76 · 759fd76
2 parents 6d9d0af + bf3e6e3
commit 759fd76
Show file tree

Hide file tree

Showing 3 changed files with 101 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -1,28 +1,74 @@
-# ocrd_imageconvert/
+# ocrd_imageconvert
 
 > Thin wrapper around convert(1)
 
 ## Introduction
 
-```sh
-# Actual conversion
-convert "$infile" "$outfile"
-```
-### What it could do
-
-[One or more of these](http://www.fmwconcepts.com/imagemagick/textcleaner/index.php) or
-[these](http://web.archive.org/web/20110517204536/http://www.ict.griffith.edu.au/anthony/graphics/imagick6/quantize/)
-or convert to grayscale, binarize etc. With threshold configurable as a
-parameter.
+[ImageMagick's](https://imagemagick.org) `convert` CLI contains a treasure trove of image operations. This wrapper aims to provide much of that as an [OCR-D compliant processor](https://ocr-d.github.io/CLI).
 
 ## Installation
 
-```
-make install
-```
+This module requires GNU make (for installation) and the ImageMagick command line tools (at runtime). On Ubuntu 18.04 (or similar), you can install them by running:
+
+    sudo apt-get install make
+    sudo make deps-ubuntu # or: apt-get install imagemagick
+
+Moreover, an installation of [OCR-D core](https://github.com/OCR-D/core) is needed:
+
+    make deps # or: pip install ocrd
+
+This will install the Python package `ocrd` in your current environment. (Setting up a [venv](https://ocr-d.github.io/docs/guide#python-setup) is strongly recommended.)
+
+Lastly, the provided shell script `ocrd-im6convert` works best when copied into your `PATH`, referencing its ocrd-tool.json under a known path. This can be done by running:
+
+    make install
+
+This will copy the binary and JSON file under `$PREFIX`, which variable you can override to your needs. The default value is to use `PREFIX=$VIRTUAL_ENV` if you have already activated a venv, or `PREFIX=$PWD/.local` (i.e. under the current working directory).
 
 ## Usage
-...
+
+This package provides `ocrd-im6convert` as a [OCR-D processor](https://ocr-d.github.com/cli) (command line interface). It uses the following parameters:
+
+```JSON
+    "ocrd-im6convert": {
+      "executable": "ocrd-im6convert",
+      "categories": ["Image preprocessing"],
+      "steps": ["preprocessing/optimization"],
+      "description": "Convert and transform images",
+      "input_file_grp": [
+        "OCR-D-IMG"
+      ],
+      "output_file_grp": [
+        "OCR-D-IMG"
+      ],
+      "parameters": {
+        "input-options": {
+          "type": "string",
+          "description": "e.g. -density 600x600 -wavelet-denoise 1%x0.1",
+          "default": ""
+        },
+        "output-format": {
+          "type": "string",
+          "description": "Desired media type of output",
+          "required": true,
+          "enum": ["image/tiff", "image/jp2", "image/png"]
+        },
+        "output-options": {
+          "type": "string",
+          "description": "e.g. -resample 300x300 -alpha deactivate -normalize -despeckle -noise 2 -negate -morphology close diamond",
+          "default": ""
+        }
+      }
+    }
+```
+
+Cf. [IM documentation](https://imagemagick.org/script/command-line-options.php) or man-page `convert(1)` for formats and options.
+
+### Example
+
+    ocrd-im6convert -I OCR-D-IMG -O OCR-D-IMG-SMALL -p '{ "output-format": "image/png", "output-options": "-resize 24%" }'
+
+(This downscales the images in the input file group `OCR-D-IMG` to 24% and stores them as PNG files under the output file group `OCR-D-IMG-SMALL`.)
 
 ## Testing
 

diff --git a/ocrd-im6convert b/ocrd-im6convert
@@ -1,37 +1,53 @@
 #!/bin/bash
+# shellcheck disable=SC2086
 
 set -eu
 set -o pipefail
 
 which ocrd >/dev/null 2>/dev/null || { echo "ocrd not in \$PATH. Panicking"; exit 1; }
 
-SHAREDIR=$(cd $(dirname $0);pwd)
+SHAREDIR="$(cd "$(dirname "$0")" >/dev/null && pwd)"
 
-declare -A output_extensions=(
-    ['image/tiff']='.tif'
-    ['image/jp2']='.jp2'
-    ['image/png']='.png'
-)
+MIMETYPE_PAGE=$(ocrd bashlib constants MIMETYPE_PAGE)
+declare -A MIME_TO_EXT
+eval "MIME_TO_EXT=( $(ocrd bashlib constants MIME_TO_EXT) )"
 
-main () {
+# FIXME: add a bashlib wrapper for logging to use here
+function log {
+    echo >&2 "$(date +%T.%3N) $LEVEL ocrd-im6convert - $1"
+}
+function critical { LEVEL=CRITICAL log "$1"; }
+function error { LEVEL=ERROR log "$1"; }
+function warning { LEVEL=WARNING log "$1"; }
+function info { LEVEL=INFO log "$1"; }
+function debug { LEVEL=DEBUG log "$1"; }
 
-    # Initialize the script
-    source `ocrd bashlib filename`
+main () {
+    # Load ocrd bashlib functions
+    # shellcheck source=../core/ocrd/bashlib/lib.bash
+    source $(ocrd bashlib filename)
 
     # Describe calling script to lib.bash
     ocrd__wrap "$SHAREDIR/ocrd-tool.json" "ocrd-im6convert" "$@"
 
     cd "${ocrd__argv[working_dir]}"
+    page_id=${ocrd__argv[page_id]:-}
     in_file_grp=${ocrd__argv[input_file_grp]}
     out_file_grp=${ocrd__argv[output_file_grp]}
     mkdir -p $out_file_grp
 
     # Set output extension
-    local output_extension="${output_extensions[${params['output-format']}]}"
+    local output_extension
+    output_extension="${MIME_TO_EXT[${params['output-format']}]}"
+    # Set input and output options
+    local input_options output_options
+    input_options=(${params['input-options']})
+    output_options=(${params['output-options']})
 
     # Download the files and do the conversion
     local IFS=$'\n'
     files=($(ocrd workspace find \
+        ${page_id:+-g} ${page_id:-} \
         -G $in_file_grp \
         -k local_filename \
         -k ID \
@@ -51,7 +67,7 @@ main () {
         local pageid="${fields[2]:-}"
 
         if ! test -f "$in_file"; then
-           echo "ERROR: input file \"$in_file\" ID=${in_id} (pageId=${pageid}) is not on disk" >&2
+           error "input file \"$in_file\" ID=${in_id} (pageId=${pageid}) is not on disk"
            continue
         fi
 
@@ -63,7 +79,8 @@ main () {
         local out_file="$out_file_grp/${out_id}$output_extension"
 
         # Actual conversion
-        convert "$in_file" "$out_file"
+        info "processing image input file $in_id ($pageid)"
+        convert "${input_options[@]}" "$in_file" "${output_options[@]}" "$out_file"
 
         # Add the output files
         declare -a options

diff --git a/ocrd-tool.json b/ocrd-tool.json
@@ -1,6 +1,6 @@
 {
   "git_url": "https://github.com/OCR-D/ocrd_im6convert",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "tools": {
 
     "ocrd-im6convert": {
@@ -15,11 +15,21 @@
         "OCR-D-IMG"
       ],
       "parameters": {
+        "input-options": {
+          "type": "string",
+          "description": "e.g. -density 600x600 -wavelet-denoise 1%x0.1",
+          "default": ""
+        },
         "output-format": {
           "type": "string",
           "description": "Desired media type of output",
           "required": true,
           "enum": ["image/tiff", "image/jp2", "image/png"]
+        },
+        "output-options": {
+          "type": "string",
+          "description": "e.g. -resample 300x300 -alpha deactivate -normalize -despeckle -noise 2 -negate -morphology close diamond",
+          "default": ""
         }
       }
     }