imgruler

#! /bin/sh

# Script to draw a ruler into an image. Intended for microscope captures.
# Needs ImageMagick: https://www.imagemagick.org/
# Published under free MIT license. Feel free to use it for whatever you like to.

round() {
  # round up or down at 0.5. Usage: `echo 4.5 | round`
  awk '{print int($1+0.5)}'
}
imgruler_help() {
  echo "Draw a ruler into an image.
Ein Lineal in ein Bild zeichnen.

Usage: imgruler [OPTIONS] [IMAGENAME]

Does not overwrite source file IMAGENAME.
Multiple IMAGENAMEs or wildcards * ? can be given. (E.g. pic*.jpg).
Without IMAGENAME a new image ruler.png with a ruler only will be created.

Quelldatei IMAGENAME wird nicht überschrieben.
Es können mehrere Quelldateien oder Wildcards mit * ? übergeben werden.
Ohne Angabe eines Bildnamens wird nur ein Linealbild ruler.png erzeugt.

Needs ImageMagick:    https://www.imagemagick.org
Benötigt ImageMagick.

Options: All options expect an argument.
Without options (or -h only) this help is displayed.

Optionen: Alle Optionen erwarten eine Wertangabe.
Ohne Optionen (oder nur mit -h) wird diese Hilfe angezeigt.
     
 -u   Real world size [and unit] of one element. Example: 5µm
      Reale Länge [und Längeneinheit] eines Linealelementes. Beispiel: 5µm
      Default: 10
 -w   Pixel width of one element. 
      Floating values like 7.4 are allowed. Element line positions
      will be rounded within the full ruler length. 
      Breite in Pixel für ein Linealelement. Nachkommastellen sind nötig
      für exakte Gesamtlänge des Lineales. Einzelstriche werden gerundet.
      Default: 10
 -h   Pixel height of one element. Ruler height will be 5 times this height.
      Höhe in Pixel für ein Linealelement. Das Lineal ist 5 mal so hoch.
      Default: Same as element width / Gleich mit Pixelbreite des Elements.
 -n   Number of elements of the ruler. Determines its length.
      Anzahl der Linealelemente. Bestimmt die Länge des Lineals.
      Default: 100
                  
 -x   X position of ruler. Default: center of image.
      X Position des Lineals. Default: Mitte.
 -y   Y position of ruler. Default: bottom of image.
      Y Position des Lineals. Default: Unterer Bildrand.
 
 -t   Title of image / Überschrift
 
 -c   Color of ruler / Farbe des Lineals.
      Default: black. Possible e.g. white, red.
 -p   Font point size. Default: twice the element height.
      Schriftgröße. Default: Das Doppelte der Elementhöhe.
 -f   Font to use. Get a list with: $Magick convert -list font | grep 'Font:'
      Schriftart. Liste: $Magick convert -list font | grep 'Font:'
 -b   Background color of empty ruler images.
      Hintergrundfarbe für leeres Linealbild ruler.png.
      Default: white. Possible e.g.: transparent
                    
 -m   Run with a predefined calibrated parameter set.
      (Define your own parameter sets in imgruler_calibrated().)
      Kalibrierte Voreinstellungswerte nutzen.
      (Setze Deine kalibrierten Werte in Funktion imgruler_calibrated().)
                  
 -o   Output file. 
        Default: Source file with '.ruler' added before file suffix.
        Default without source file: ruler.jpg
      Bildname für neues Bild mit Lineal.
        Default: IMAGENAME.ruler.ENDUNG
        Default ohne IMAGENAME: ruler.png
"
}
imgruler() {
  local Sourcefile Destinationfile Sourcefilelist Destinationfilelist
  local Elementsize Elementunit Elementwidth Elementcount Elementheight
  local Linesstring Labelstring Pointsize Color Font
  local Xpos Ypos Xoffset Imagewidth Imageheight
  local Magick Line Options Optioncount=0
  local Tabulator="$(printf "\t")"
  
  Magick="$(command -v magick)"
  [ "$Magick" ] || {
    convert -version | grep -q ImageMagick || {
      echo "Need convert utility from ImageMagick. convert not found. Exit." >&2
      return 1
    }
  }
  Imdisplay="$(command -v imdisplay)"
  [ "$Imdisplay" ] || Imdisplay="display"
  
  # Show help if -h or no options are given
  { [ -z "$*" ] || [ "$*" = "-h" ] ; } && {
    imgruler_help
    return 1
  }

  # check options
  while getopts ":u:w:h:n:o:c:p:b:x:y:m:f:t:" Option; do
    case "$Option" in
      u)                                              # Unit size and identifier, e.g. 5µm
         Elementunit="$(echo "${OPTARG:-}" | sed 's/[.0-9]*//g')"
         Elementsize="${OPTARG%$Elementunit}"
      ;;
      w) Elementwidth="${OPTARG:-$Elementwidth}"  ;;   # Pixel width of one element. Floating values allowed.
      h) Elementheight="${OPTARG:-$Elementheight}" ;;  # Pixel height of one element.
      n) Elementcount="${OPTARG:-$Elementcount}" ;;    # Number of desired elements (=length of ruler)
      
      x) Xpos="${OPTARG:-}" ;;                         # X position of ruler
      y) Ypos="${OPTARG:-}" ;;                         # Y position of ruler
      
      t) Title="${OPTARG:-$Title}" ;;                  # Title
      p) Pointsize="${OPTARG:-$Pointsize}" ;;          # Font point size
      f) Font="${OPTARG:-$Font}" ;;                    # Font
      c) Color="${OPTARG:-$Color}" ;;                  # Color of ruler
      b) Background="${OPTARG:-$Background}" ;;        # Background color for ruler-only images
      
      m) imgruler_calibrated "${OPTARG:-}" ;;          # Set parameters predefined in ruler_calibrated()
      
      o) Destinationfile="${OPTARG:-}" ;;              # Output file.
      
      ?) echo "ERROR: Unkown option: -$OPTARG
" >&2
         imgruler_help >&2
         return 1 ;;
    esac
    Optioncount=$((Optioncount + 1))
  done
  
  Option=1
  while [ "$Option" -le "$Optioncount" ]; do
    shift
    shift
    Option=$((Option + 1))
  done
  
  # check input files
  while [ $# -gt 0 ]; do
    Sourcefilelist="$Sourcefilelist$Tabulator${1:-}"
    [ -e "${1:-}" ] || {
      echo "ERROR: File not found: ${1:-}"
      return 1
    }
    shift
  done
  
  # Default values if not already set
  Elementsize="${Elementsize:-10}"
  Elementwidth="${Elementwidth:-10}"
  Elementheight="${Elementheight:-$(echo "$Elementwidth" | round)}"
  Elementcount="${Elementcount:-100}"
  Pointsize="${Pointsize:-$((Elementheight * 2))}"
  Color="${Color:-black}"
  Background="${Background:-white}"
  Title="${Title:-}"

  [ "$Sourcefilelist" ] || {
    # No source file? Create empty image with ruler only.
    echo "Will create a new empty image with a ruler in it."
    Imagewidth="$(awk "BEGIN {print $Elementwidth * $((Elementcount +14))}" | round)"
    Imageheight="$((Elementheight * 7))"
    Destinationfile="${Destinationfile:-ruler.png}"
    $Magick convert -size ${Imagewidth}x${Imageheight} xc:$Background "$Destinationfile"
    Sourcefilelist="$Destinationfile"
  }

  IFS="$Tabulator"
  for Sourcefile in $Sourcefilelist ; do
    
    Imagewidth=$($Magick identify -format "%w" "$Sourcefile")
    Imageheight=$($Magick identify -format "%h" "$Sourcefile")
    #Destinationfile="${Destinationfile:-$(dirname "$Sourcefile")/ruler_$(basename "$Sourcefile")}"
    [ "$Destinationfile" ] || {
      Destinationfile="$(echo "$Sourcefile" | rev | cut -d. -f2- | rev).ruler.$(echo "$Sourcefile" | rev | cut -d. -f1 | rev)"
    }

    [ "$Xpos" ] || Xpos=$(awk "BEGIN {print $Imagewidth/2 - $Elementwidth * $Elementcount /2}" | round)
    [ "$Ypos" ] || Ypos=$Imageheight

    Line=0
    while [ "$Line" -le "$Elementcount" ] ; do   # small lines
      Xoffset=$(awk "BEGIN {print $Elementwidth * $Line}" | round)
      Linesstring="$Linesstring line $((Xpos + Xoffset)),$Ypos $((Xpos + Xoffset)),$((Ypos - Elementheight * 1))"
      Line=$((Line+1))
    done
    Line=0
    while [ "$Line" -le "$Elementcount" ] ; do   # half lines
      Xoffset=$(awk "BEGIN {print $Elementwidth * $Line}" | round)
      Linesstring="$Linesstring line $((Xpos + Xoffset)),$Ypos $((Xpos + Xoffset)),$((Ypos - Elementheight * 2))"
      Line=$((Line+5))
    done
    Line=0
    while [ "$Line" -le "$Elementcount" ] ; do   # long lines
      Xoffset=$(awk "BEGIN {print $Elementwidth * $Line}" | round)
      Linesstring="$Linesstring line $((Xpos + Xoffset)),$Ypos $((Xpos + Xoffset)),$((Ypos - Elementheight * 3))"
      Labelstring="$Labelstring text $((Xpos + Xoffset - Pointsize)),$((Ypos - Elementheight * 3 -2)) '$(awk "BEGIN {print $Line * $Elementsize}")$Elementunit'"
      Line=$((Line+10))
    done

    # Find a font
    [ "$Font" ] || Font="$($Magick convert -list font | grep Font: | cut -d: -f2 | grep -i -E 'arial|helvetica|times-roman|times-new-roman' | sort | head -n1 )"
    Font="$(echo $Font | sed 's/ //g')"

    #Create the ruler
    echo "Creating $Destinationfile"
    $Magick convert "$Sourcefile" \
            -fill $Color -draw "$Linesstring" \
            -fill $Color -font $Font -pointsize $Pointsize -draw "$Labelstring" \
            -gravity north -draw "text 0,10 '$Title'" \
            "$Destinationfile"
            
    Destinationfilelist="$Destinationfilelist$Tabulator$Destinationfile"
    Destinationfile=""
  done
  # show created images
  #env IFS="$Tabulator" $Imdisplay $Destinationfilelist
}
imgruler_calibrated() {
  # English:
  # Predefined parameter sets calibrated to my microscope capture results.
  # Can be used with e.g.: imgruler -m 100c
  # Adjust for your own camera results checked with micrometer captures.
  # Most important:
  #  Option -u sets Elementsize and Elementunit
  #  Option -w sets Elementwidth
  #  Option -n sets Elementcount
  # How to calibrate:
  #  - Set your camera to your desired image resolution that you want to use regulary.
  #  - Capture an image of a micrometer.
  #  - Run imgruler with options -x 100 -y 100
  #  - Change -x and -y until the first 0 line of the ruler meets a micrometer line
  #  - Try out several values for -w (width of one element) until the ruler lines match the micrometer in a useful way. 
  #    Use floating values like -w 7.48 for fine tuning.
  #  - Set option -u 5µm. Change the value until the ruler values match the measured size.
  #  - Remove options -x and -y.
  #  - Set option -n 40. Change value until ruler length looks nice to you.
  #  - You can further adjust ruler height with -h or font size with -p if you like to.
  #  - Create an entry below that matches your measured values. Give it a name that means something to you.
  #  - You can use your created entry with e.g. -m 100c
  #
  # Deutsch:
  # Eigene kalibrierte Werte für die Option -m. Beispielaufruf: imgruler -m 100p bildname.jpg
  # Bitte trage hier eigene Namen und Werte ein nach dem Vorbild der Beispiele.
  # Am wichtigsten:
  #   Elementsize    Reale Länge eines Linealelements, z.B. 5
  #   Elementunit    Einheit des Lineals, z.B. µm
  #   Elementwidth   Breite in Pixel einer Linealeinheit. Nachkommastellen möglich und nötig für genaue Kalibrierung
  #   Elementcount   Anzahl der Linealelemente. Effektiv die Länge des Lineals.
  # Außerdem möglich, aber nicht nötig:
  #   Elementheight  Höhe eines Elementes
  #   Pointsize      Schriftgröße
  #   Color          Farbe
  #   Font           Schriftart
  #   Background     Hintergrundfarbe für Lineal ohne Bild
  #
  # Vorgehensweise beim Kalibrieren:
  #  - Kamera auf die gewollte/übliche Bildauflösung einstellen.
  #  - Eine Aufnahme von einem Mikrometer machen.
  #  - Mit Positionsoptionen -x und -y starten.
  #    Beispiel: imgruler -x 100 -y 100 bildname.jpg
  #  - Die Werte von -x und -y anpassen, bis der Anfang des Lineals eine Linie des Mikrometers trifft.
  #    Beispiel: imgruler -x 196 -y 240 bildname.jpg
  #  - Verschiedene Werte für -w (Pixelbreite eines Elements) ausprobieren, 
  #    bis die Hauptlinien des Lineals mit dem Mikrometer deckungsgleich sind.
  #    Beispiel: imgruler -x 196 -y 240 -w 7.48 bildname.jpg
  #  - Größe und Einheit eines Linealelementes mit -u festlegen.
  #    Beispiel: imgruler -x 196 -y 240 -w 7.48 -u 2µm bildname.jpg
  #  - Sobald das Lineal gut zum Mikrometer paßt: Positionsangaben -x und -y entfernen.
  #  - Länge des Lineals mit -n festlegen, bis es optisch gefällt und sinnvoll ist.
  #    Beispiel: imgruler -w 7.48 -u 2µm -n 50 bildname.jpg
  #  - In der case-Abfrage unten eigene Namen mit den kalibrierten Werten eintragen.
  #    Dabei an den Beispieleinträgen orientieren.
  #  - Mit der Option -m und dem definierten Namen werden die kalibrierten Werte gesetzt.
  #    Beispiel: imgruler -m 100p bildname.jpg
  #
  case "${1:-}" in
    100c) # 1000x900
      Elementsize="1"
      Elementunit="µm"
      Elementwidth="18.7"
      Elementcount="100"
      Elementheight="37"
      Pointsize="37"
    ;;
    100p) # 196x240
      Elementsize="2"
      Elementunit="µm"
      Elementwidth="7.48"
      Elementcount="50"
    ;;
    100z) # 131x440
      Elementsize="1"
      Elementunit="µm"
      Elementwidth="18.5"
      Elementcount="30"
      Elementheight="14"
      Pointsize="18"
    ;;
    40c) # 1252x1000
      Elementsize="5"
      Elementunit="µm"
      Elementwidth="37.4"
      Elementcount="40"
      Pointsize="37"
    ;;
    40p) # 246x240
      Elementsize="5"
      Elementunit="µm"
      Elementwidth="7.48"
      Elementcount="40"
    ;;
    40z) # 78x290
      Elementsize="1"
      Elementunit="µm"
      Elementwidth="7.48"
      Elementcount="50"
      Elementheight="19"
      Elementheight="14"
      Pointsize="18"
    ;;
    20c) # 1186x1200
      Elementsize="10"
      Elementunit="µm"
      Elementwidth="37.34"
      Elementcount="50"
      Pointsize="37"
    ;;
    20p) # 232x240
      Elementsize="10"
      Elementunit="µm"
      Elementwidth="7.48"
      Elementcount="50"
    ;;
    20z) # 196x390
      Elementsize="5"
      Elementunit="µm"
      Elementwidth="18.65"
      Elementcount="20"
      Elementheight="14"
      Pointsize="18"
    ;;
    10c) # 1026x1200
      Elementsize="10"
      Elementunit="µm"
      Elementwidth="18.5"
      Elementcount="100"
      Elementheight="37"
      Pointsize="37"
    ;;
    10p) # 200x230
      Elementsize="20"
      Elementunit="µm"
      Elementwidth="7.39"
      Elementcount="50"
    ;;
    10z) # 188x350
      Elementsize="5"
      Elementunit="µm"
      Elementwidth="9.23"
      Elementcount="40"
    ;;
  esac
}

imgruler "$@"