UP | HOME

# Anaglyph HALD Generator (Anahald) - Auto-choice of a LUT for stereopair

By Oleg Kosyakovsky

## Table of Contents

- Functionality
- Pre-requisites and installation
  - Python
  - ImageMagick
  - Code- and Data files
- Usage
  - Command-line for Windows command-prompt
  - Command-line for BASH on Windows or Linux
  - Drag-and-drop on Windows
- Re-training the model - for computer geeks
  - Input requirements for training
    - Helper procedure to generate filename-to-HALD map CSV
  - Invoking the training procedure
  - Locating training outputs

Automatic choice of a HALD-LUT for a given stereopair is facilitated by a neural network (ResNet-18) trained on the author's test-image dataset. It runs on Python and uses ImageMagick for actual image processing. Accuracy achieved by its training is 96.5%.
The author uses Anahald auto-choice on Windows; some basic testing preformed on Linux too.

## Functionality

Anahald auto-choice is a command-line utility that accepts stereopair (SBS) image and outputs anaglyph made with an Anahald LUT that suites it best.
On Windows one can use Anahald auto-choice in drag-and-drop manner as well.
The utility is based on neural network "ResNet-18" implemented in Python and trained from scratch on the author's stereo-image dataset.
At the time of this writing the accuracy of Anahald auto-choice is good though not ideal. But it does make reasonable choices for absolute majority of images, thus saving lots of postprocessing time to the user.

## Pre-requisites and installation

### Python

Required are Python interpreter and the following libraries: torch, torchvision, pandas.
The need for additional libraries complicates use-cases where the libraries are installed under virtual environments.
Having said the above, most Python installations should support command-line usage scenario - when the user first opens the console window with the required environment, then types commands into it.
On contrary, drag-and-drop kind of usage requires to start python under the hood, so that there's no chance to request a particular environment.

The author succeeded to use drag-and-drop only with WinPython on Windows, while command line worked under WinPython and Anaconda on Windows, and under pre-installed Python 3.8 under WSL-Linux.

If you are on Linux, Python is most probably preinstalled; otherwise follow the installation procedure of your Linux distribution.
If you are on Windows, the author's recommendation is to install WinPython - it should handle both command-line and drag-and-drop usage approaches.

Do install the 3 additional libraries - torch, torchvision, pandas - by issuing the three "pip install LIBRARY-NAME" commands at the OS prompt (i.e. CMD on Windows, BASH on Unix):

- On Windows it should be CMD terminal associatd with your Python installation - like "WinPython Command Prompt" for WinPython, "Anaconda Termimal" for Anaconda-Python.
- On Linux it should be a regular BASH prompt.

The last step is to "help" Anahald auto-choice in finding the appropriate Python interpreter. This is achieved by one-line scripts Code/Choice/python.bat and Code/Choice/python.sh that invoke Python interpreter by absolute path while passing it all command-line arguments.
The distribution includes 3 examples of such files:

- Code/Choice/python.bat.EXAMPLE - for use with DOS-CMD scripts on Windows
- Code/Choice/python.sh.EXAMPLE-WINDOWS - for use with BASH scripts on Windows
- Code/Choice/python.sh.EXAMPLE-Linux - for use with BASH scripts on Linux

Copy the relevant example into script named Code/Choice/python.bat or Code/Choice/python.sh accordingly, and change the path to match your system.
Note that Linux example doesn't include absolute path; it relies on the system PATH instead; it's fine on Linux where it's unlikely to have multiple installations of Python

### ImageMagick

See Obtaining ImageMagick for installation instructions.
After installing ImageMagick, find the path of its main utility - "magick[.exe]" for newer versions or "convert[.exe]" for older versions.
You need to define environment variable IMAGEMAGICK_CONVERT_OR_MAGICK to contain the above path.
If ImageMagick is included in the system PATH variable, IMAGEMAGICK_CONVERT_OR_MAGICK can contain just "magick[.exe]" or "convert[.exe]"; otherwise absolute path is required. The former option is typical of Linux systems, while the latter is more suitable for Windows.

### Code- and Data files

Anahald auto-choice expects a hardcoded folder hierarchy to locate its code- and data files:

      Directory arrangement:
    ----------------------
          +---SAMPLE_HALDS
          |   |   hald__ahg_oleg_cp__16.TIF
          |   |   hald__ahg_oleg_ec__16.TIF
          |   |   hald__ahg_oleg_gp__16.TIF
          |   |   hald__ahg_oleg_sf__16.TIF
          |   |
          |   +---ADD
          |           hald__ahg_oleg_mc__16.TIF
          |           hald__ahg_oleg_xc__16.TIF
          |
          +---Code
          |   |
          |   +---Choice
          |   |   (Python code files)
          |   |   choose_hald_for_image.bat
          |   |   choose_hald_for_image.sh
          |   |   python.bat
          |   |   python.sh
          |
          +---CHOICE_MODELS
          |   |   anahald_label_codes__96d5__20250814-231159.csv
          |   |   anahald_model_params__96d5__20250814-231159.pth
          |

- Anahald choice code is a part of Anahald distribution; follow the instructions in Anahald installation guide if you didn't do it yet.
- Download Anahald premade LUTs - sample HALDs here and place them under directory ..\..\SAMPLE_HALDS\ relative to location of 'choose_hald_for_image.bat'.
- Download Anahald choice model files here and place them under directory ..\..\CHOICE_MODELS\ relative to location of 'choose_hald_for_image.bat'.

## Usage

Command lines for the two shells are described below. The parameters for both are semantically identical, but differ in path syntax:

- Windows CMD expects directory separators as "\" and drive names like "C:\"
- BASH expects directory separators as "`/`" and drive names like "`/C/`"

### Command-line for Windows command-prompt

choose_hald_for_image.bat INPUT-SBS-IMAGE-GLOB-1 … INPUT-SBS-IMAGE-GLOB-n [/OUTPUT-DIRECTORY/]

- INPUT-SBS-IMAGE-GLOB - either path of SBS image file, or glob pattern matching one or more such files; e.g. the script obtains either list of input files, or one or more glob patterns matching those
- OUTPUT-DIRECTORY - optional path of the output directory for resulting anaglyphs; if not given, defaults to "ANA\" subdirectory under the location of input file(s)

### Command-line for BASH on Windows or Linux

choose_hald_for_image.sh INPUT-SBS-IMAGE-GLOB-1 … INPUT-SBS-IMAGE-GLOB-n [/OUTPUT-DIRECTORY/]

- parameters are the same as for Windows CMD; only path syntax differ

Example (BASH on Windows):

    /c/Oleg/GitWork/AnaHald/Code/Choice/choose_hald_for_image.sh  /G/Photo_Archive/Photos_5/Israel_2016/Stereo/241216__Akko3D/SBS/*.TIF  /y/TMP

### Drag-and-drop on Windows

Drag-and-drop invocation differs in having no provision to supply command arguments other than list of input files. For this reason output directory will always be "ANA\" subdirectory under the location of input file(s), and glob patterns aren't supported.
For convenience, the author's recommendation is to place shortcut to choose_hald_for_image.bat on the desktop.
After one or more input images are dropped onto the shortcut, a new DOS-CMD window opens where operation log is printed. If anything goes wrong, examine error and warning messages in this window.
When the script finishes, "Press Enter to close…" prompt appears in the bottom of the above log window. Do not press Enter if you want to read the log.

## Re-training the model - for computer geeks

The author's dataset included ~620 labeled(!) images, augmented to ~1860 by blurring and sharpening. The result is usable but leaves space for improvement.
A user with a larger dataset or different preferences may benefit by re-training auto-choice model.
As re-training is considered the "toy" for the most advanced users, there are no OS shell wrappers - the procedure is invoked from Python-interpreter prompt.

### Input requirements for training

1. A collection of SBS stereopairs

2. A CSV file that maps between the above stereopair filenames and sample HALD LUTs chosen for them. Example of a CSV file:

       $ head -6 sbs_to_hald.csv
       SbsFileName,HaldId
       DSC00022-00034,ahg_oleg_cp
       DSC00033,ahg_oleg_gp
       DSC00035,ahg_oleg_gp
       DSC00037,ahg_oleg_gp
       DSC00040-00564,ahg_oleg_sf

#### Helper procedure to generate filename-to-HALD map CSV

CSV file mentioned above could be generated by MapSbsToHalds() Python procedure given a directory with anaglyph images named "<FILE-ID>[_<HALD-ID>].jpg (example: "DSC00037_ahg_oleg_gp.jpg").

- Images with "_<HALD-ID>" suffix are mapped to corresponding HALD.
- Images without "_<HALD-ID>" suffix are mapped to the identity HALD - "ahg_oleg_id".

Example of invocation of MapSbsToHalds(); includes loading the Python code:

    import sys;  sys.path.append('C:\\Oleg\\Gitwork\\Anahald\\Code\\Choice')
    from choose_hald_resnet import *

    ANADIR='D:\\Work\\RMA_WA\\OUT\\Anaglyph_RR\\ANAGLYPHS;  haldDict = MapSbsToHalds(ANADIR, outCsvPathOrEmpty="TMP/sbs_to_hald.csv");  len(haldDict)

### Invoking the training procedure

Here it's assumed that you have Anahald installed (which includes auto-choice) - e.g. Pre-requisites and installation section is completed.

- Arrange Python environment, preferably with CUDA videocard processor(s), install libraries torch, torchvision, and pandas.
  - in order to have CUDA available, you may need Python interpreter different from the one used for auto-choice invocations
- In code file "choose_hald_base.py" change the target accuracy - training stops and stores the results when accuracy indicated by "SUFFICIENT_ACCURACY_TO_STOP" variable is achieved.

- As shown in the following example, load the code into the above Python shell and start training. Note the addition of Python-code path to sys.path; do provide the path that matches your Anahald installation.

      import sys;  sys.path.append('C:\\Oleg\\Gitwork\\Anahald\\Code\\Choice')
      from choose_hald_resnet import *

      TrainAnahaldResnet('sbs_to_hald.csv', 'ALL_SBS_1080', num_epochs=100)

  Comments for the example:

  - directory added to sys.path is the one where "choose_hald_resnet.py" is located
  - 'sbs_to_hald.csv' is the path of CSV file mapping stereopair filenames to HALD identifiers
    - the HALD identifier is not its filename; for example sample HALD file "hald__ahg_oleg_cp__16.TIF" has identifier "ahg_oleg_cp"
  - 'ALL_SBS_1080' is the path of a directory with input stereopair images

### Locating training outputs

Two files constitute training output; the <TIMESTAMP> fields in their names must be equal:

1. "anahald_model_params__<TIMESTAMP>.pth" - the trained model parameters
2. "anahald_label_codes__<TIMESTAMP>.csv - maps internal label codes to HALD identifiers

Anahald training reports the paths of output files; watch for messages like:

    -I- Saved model in 'MODELS\anahald_model_params__20250817-221920.pth'
    -I- Success saving dictionary in 'MODELS\anahald_label_codes__20250817-221920.csv

Copy the two files into "CHOICE_MODELS" directory (see Code- and Data files).
Update the model filename in "choose_hald_for_image.py" - change the assignment of variable "MODEL_FILENAME", e.g.:

    MODEL_FILENAME = "anahald_model_params__20250817-221920.pth"

Now everything is set to run auto-choice with the new model.

Oleg Kosyakovsky

Haifa, Israel

2024-2025