slideRename - swvanderlaan/slideToolKit GitHub Wiki

slideRename is designed to display thumbnails from a list of given whole-slide images (WSI) and opens a terminal window for manual renaming. Users can interactively rename images by entering the new filename. The script ensures that the renaming process is done carefully, and it provides a manual intervention step to avoid overwriting existing files with the same name.

Two versions are available:

• This is a bash implementation.
• This is a python3 implementation which is much faster than the bash version.

This bash version is designed to use ImageMagick's convert command, as well as the dmtxread and wmctrl libraries to rename WSI files. It can optionally use ImageMagick or macOS Preview.app to preview the file.

• Basic usage

./slideRename -f "file.tif"

• Set prefix, suffix, and file

./slideRename --prefix="AE" --suffix=".CD68.\${RANDOM}" --file="file.tif"

• Specify layer and additional convert arguments

./slideRename --layer=5 --convert-args="-rotate 90" -f "file.tif"

• Print a job list for automatic renaming with barcode

find "$(pwd)" -iname "*.tif" -exec "./slideRename" --barcode="dmtx" --to-upper --preview="none" -f="{}" \;

• Print a job list for manual renaming with OS X Preview

find "$(pwd)" -iname "*.tif" -exec "./slideRename" --to-upper --preview="osx" -f="{}" \;

Argument(s):

• -f, --file <filename>
  • Specifies the virtual slide to rename.

Optional argument(s):

• -l, --layer <integer>
  • Forces a specific layer by layer id.
• --prefix <text>
  • Sets the filename prefix.
• --suffix <text>
  • Sets the filename suffix.
• --to-lower
  • Transforms filename output to lowercase.
• --to-upper
  • Transforms filename output to uppercase.
• --barcode dmtx|zbar
  • Finds barcode (by library) and renames accordingly.
• --resize <widthxheight>
  • Sets preview dimensions.
• --convert-args='<arguments>'
  • Sets convert arguments for image manipulation.
• --preview im|osx|none
  • Displays a preview miniature using ImageMagick, OS X Preview.app, or none.
• --wmctrl-timeout <seconds>
  • Sets window switching timeout.
• --ignore-dependencies
  • Ignores missing dependencies but gives a warning.
• --help
  • Displays the help message.
• --version
  • Displays version and license information.

Example usage:

python slideRename.py --input AE1234.SR.ndpi

Argument(s):

• -i, --input
  • Provide a single WSI or list of WSIs. Required.

Optional argument(s):

• -o, --outdir
  • Specifies the output directory for saving renamed images (default is the input image(s) directory). Optional.
• --prefix
  • Prepends a string to the output filename (default: none). Optional.
• -s, --suffix
  • Appends a suffix to the end of the file (no suffix is added by default). Optional.
• --case {none,lower,upper}
  • Sets filename casing (default: none = unchanged). Optional.
• --to-upper / --to-lower
  • Aliases for forcing uppercase or lowercase output (overrides --case). Optional.
• --barcode {auto,dmtx,zbar,off}
  • Barcode decoding mode (default: auto).
    • dmtx → DataMatrix codes (via pylibdmtx)
    • zbar → QR/Code128/EAN/etc. (via pyzbar)
    • off → skip barcode decoding
• --preview {cv2,none}
  • Controls preview window (default = cv2). Use none for headless/batch mode. Optional.
• --resize WxH
  • Resizes the label/macro image for faster preview/decoding (e.g., --resize 800x600). Optional.
• --rotate {0,90,180,270}
  • Rotates the label/macro image before preview and barcode decoding (default = 90). Optional.
• --dry-run
  • Prints the planned rename operations without moving any files. Optional.
• -f, --force
  • Forces overwriting output even if it already exists. Optional.
• -v, --verbose
  • Enables detailed output (image dimensions, decoding attempts, etc.). Optional.
• -h, --help
  • Show this help message and exit. Optional.
• -V, --version
  • Display version and license information.