UP | HOME

# Anaglyph HALD Generator (Anahald) - Installation

By Oleg Kosyakovsky

## Table of Contents

- Dependencies
  - Obtaining Tcl Interpreter
  - Obtaining ImageMagick
- Obtaining Anahald
- Applying some executable path arrangements:
- Verifying Anahald setup
- Installing additional features

Anahald is made to be portable and non-intruding (no registry changes on Windows), so "installation" could amount to downloading and unzipping the stuff.
The Anahald code is written in plain Tcl, which is an interpretable language available on any platform, and no compilation is needed.

Notes on glossary:

- the author uses interchangeably the terms "folder" and "directory"; the former is misleading but widely known , the latter is technically correct but for some reason "obstructed" from the common users
- the author uses interchangeably the terms "Tcl shell" and "Tcl interpreter"
- the author uses interchangeably the terms "command-shell* and "shell*; these refer to CMD or BASH
- "LUT" means lookup table, "CLUT" means color lookup table; the author uses these two terms and terms "HALD", "HALD-LUT", "HALD-CLUT" interchangeably
- "Identity-HALD" standardly means a HALD-CLUT that maps each color to itself
- the author refers to a HALD-CLUT made by Anaglyph HALD Generator as "balanced HALD"
- the author uses interchangeably the terms "configuration file", "config file", and "config"
- the author uses interchangeably the terms "anaglyph" and "red-cyan anaglyph"
- "balancing" a color means replacing it with some related anaglyph-friendly color obtained by reducing the difference between red channel on one side, and green and blue channels on the other side
- sides-ratio is a ratio between values of red channel, and maximum of green and blue channels - the larger divided by the smaller; used as a measure of disbalance in colors

Notes on expected users' knowledge:

- the user must be familiar with the very basics of:
  - command line
  - file system
- knowledge of Tcl or any other programming language is not a requirement

## Dependencies

Anahald relies on two prerequisites to be available on the computer:

- console version of Tcl interpreter ("tclsh")
- ImageMagick suite of image-manipulation utilities

### Obtaining Tcl Interpreter

As already mentioned, we need the console-only Tcl interpreter; commonly the executable file named "tclsh.exe" or "tclsh"; the name stands for "Tcl shell"
On Linux computers Tcl is usually preinstalled.
To verify it, type tclsh into the terminal

- if Tcl is available, Tcl-shell is entered
  - if it's the case, type puts $tcl_version into the prompt you obtained; Anahald needs version 8.5 or newer
- if Tcl is not available, Linux prints commands to install it
  - just follow the suggestion and the system takes care of the rest
  - as the result Tcl becomes invocable by typing tclsh into the terminal

On Windows computers obtaining Tcl is under the user's responsibility, and there are two options:

1. Install the complete official distribution
   Official Tcl Download Link
   - note that this option involves changes to the system - registry, search path, etc
   - as the result Tcl becomes invocable by typing tclsh.exe into the prompt of CMD.EXE or BASH
2. Download a standalone self-contained executable, unzip it and begin using
   - this option is a part of the promised non-intrusive way of obtaining Anahald
   - the author's favorite standalone Tcl interpreter is "freeWrap"; it's meant for other job, but doubles nicely as a Tcl shell too
   - freeWrap could be obtained for free at freeWrap Home Page
     - download and unpack the ZIP archive
     - find freewrapTCLSH.exe under the relevant directory (win32 or win64)
     - rename it into WHATEVER-YOU-LIKE.exe, and then it becomes your Tcl interpreter
     - further in this guide the assumed name is "tclsh_fw.exe"
     - it's up to you whether to include its directory into the system search path
     - verify it by invoking as "<DIRECTORY-PATH>\tclsh_fw.exe" from CMD console
3. Now you can type puts $tcl_version into the prompt you obtained; Anahald needs version 8.5 or newer

### Obtaining ImageMagick

… copied from the mainpage of ImageMagick site:
ImageMagick is a free, open-source software suite, used for editing and manipulating digital images.
All Anahald requires from ImageMagick is one (major) command-line utility to convert between image formats. The utility's name was recently changed, creating some minor mess.

- in older versions it used to be called "convert"
- starting from version 7.??? the new name is "magick"
- Linux users may find themselves stuck with older versions

On Linux computers ImageMagick may be preinstalled.
To verify it, try to query the utility by its two names from the terminal - first as magick, then - if no luck - as convert:

Shown below is ImageMagick verification session on the author's Linux computer:

    $ magick --version
    Command 'magick' not found, did you mean:
      command 'magics' from deb magics++ (4.10.1-1)
      command 'magic' from deb magic (8.3.105+ds.1-1.1)
    Try: sudo apt install <deb name>

    $ convert --version
    Version: ImageMagick 6.9.11-60 Q16 x86_64 2021-01-25 https://imagemagick.org
    Copyright: (C) 1999-2021 ImageMagick Studio LLC
    ...

Obviously the author has an old version on his Linux.
The output above indicates that ImageMagick is installed and invocable as convert.

As with Tcl, if ImageMagick is not available, Linux prints commands to install it

- just follow the suggestion and the system takes care of the rest
- as the result ImageMagick becomes invocable from the terminal - either as magick or as convert.

On Windows computers, as with Tcl, obtaining ImageMagick is under the user's responsibility.

- ImageMagick is downloadable for free at ImageMagick Home Page
- There are multiple download formats; the author recommends to follow non-intrusive route of getting a ZIP archive:
  - pick the option tagged ""Portable Win64 static at 16 bits-per-pixel component. Just copy to your host and run (no installer, no Windows registry entries).
    - (or "… Win32 static …" - whatever is relevant)
  - unpack the ZIP archive in the directory of your choice
  - find where is either magick.exe or convert.exe
  - now it's up to you whether to include the directory of the found executable into the system search path
  - verify ImageMagick by running "<DIRECTORY-PATH>\magick.exe" –version or "<DIRECTORY-PATH>\convert.exe" –version from CMD console

## Obtaining Anahald

(The example session presented in this section comes from BASH on the author's Linux computer. It would look very similar in BASH under Windows (e.g. git-bash, etc.))

1. Download Anahald Tcl code as a ZIP archive (e.g. "Source code (zip)") from Anahald code distribution download link
2. Unzip the Anahald archive in a directory of your choice
   - the unpacked files-and-directories structure is placed under "AnaHald-release-<VERSION-TAG>" subdirectory
     - rename this subdirectory if you wish; the author's example assumes the new name is "AnaHald"

   - from now on this directory is referred to as <Anahald-Root>
     Here is how it looks:

         $ cd ~/ANY/TMP/AnaHald/
         $ tree -d .
         .
         ├── bin
         ├── CFG
         │   └── ADD
         ├── Code
         │   ├── Choice
         │   ├── img_proc
         │   ├── ok_utils
         │   ├── View
         └── Doc
             └── files
                 └── css

         10 directories
         ...
         $ ls bin/
         anahald_cfg_table.bat  anahald_lut_make.sh  demo__embed_tcl_in_dos_batch.bat
         anahald_cfg_table.sh   convert.bat.EXAMPLE  tclsh.bat.EXAMPLE
         anahald_lut_make.bat   convert.sh.EXAMPLE

     What matters for end-users, is the contents of bin/ subdirectory - where the adjustments listed below apply.

## Applying some executable path arrangements:

a) For Tcl interpreter - if on Linux

- nothing needs to be done - automatic installation ensured Tcl-shell is accessible as tclsh

b) For Tcl interpreter - if on Windows

- if your tclsh executable is named "tclsh.exe" AND its directory path is included into the system path, nothing more to be done
  - this is usually the case when the complete official Tcl distribution is installed
- in any other case place a file named "tclsh.bat" into the bin\ subdirectory
  - the "bin\\tclsh.bat" file is aimed to point at the actual tclslh executable
  - copy bin\\tclsh.bat.EXAMPLE into bin\\tclsh.bat

  - in bin\\tclsh.bat edit executable path in the line that starts with "@set TCLSH="
    Example of Tcl path pointer from the author's Windows system:

        ...
        @REM <<<<<< Please specify full path of command-line Tcl interpreter here >>>>>
        @set TCLSH="c:\Oleg\Tools\TCL\tclsh_fw.exe"
        ...

c) For ImageMagick - if on Linux

- if your main ImageMagick utility is named "magick", nothing more to be done
  - this assumes that Linux enforces standard installation scenarios, which always take care of search path
- if your main ImageMagick utility is named "convert", place a file named "convert.sh" into the bin/ subdirectory:
  1. copy bin/convert.sh.EXAMPLE into bin/convert.sh
     - the "convert.sh.EXAMPLE" essentially translates calls of "magick" into calls of "convert"

  2. give the latter executable permissions by

         chmod +x bin/convert.sh

d) For ImageMagick - if on Windows

- if your main ImageMagick utility is named "magick.exe" AND its directory path is included into the system path, nothing more to be done
  - (this would be the case if ImageMagick installer has been used - against the author's recommendation of the portable route)
- if your main ImageMagick utility is named "convert.exe" AND/OR its directory path is not included into the system path, you need to place a file named "convert.bat" into the bin\ subdirectory
  - the "bin\\convert.bat" file is aimed to point at the actual "convert.exe" or "magick.exe" executable
  - copy bin\\convert.bat.EXAMPLE into bin\\convert.bat

  - in bin\\convert.bat edit executable path in the very last non-empty line

    - e.g. only change the path string inside quotes; do not alter anything else

    Example of Imagemagick path pointer from the author's Windows system (convert.bat):

        ...
        "c:\Program Files\ImageMagick_711_3\magick.exe"  %*

Upon completing the above steps, it's the time to verify the Anahald suite.

## Verifying Anahald setup

This section is built around Anahald commands without explaining them, since their understanding isn't important at this stage. A dedicated section is Anahald User Commands.
To streamline the steps, assume the current directory to be the <Anahald-Root>

1. Check if Anahald code could at all be invoked - run without arguments - hoping to obtain usage-help message:

   - On Linux - in BASH - type:
     cd <Anahald-Root>
     bin/anahald_lut_make.sh
   - On Windows - in DOS-CMD - type:
     cd <Anahald-Root>
     bin\anahald_lut_make.bat

       $ bin/anahald_lut_make.sh
       ... Begin loading TCL code ...
       -I- Finished setup of AnaHald suite (context: 'rca_colorset.tcl')
       -I- Imagemagick convert/magick utility will be called as 'magick'
       -I- Color-ratio tuning: MIN_COLOR_VAL_FOR_RGB_RATIO=0.5;  _MIN_RGB_RATIO=0.00196078431372549;  _MAX_RGB_RATIO=510.0
       -I- Finished setup of AnaHald suite (context: 'anahald_lut_make.sh')
       ... Done  loading TCL code ...
       ============ Running Anaglyph HALD Generator under SH/BASH =============

       * Usage:  anahald_lut_make.sh  <CONFIG-PATH>  <HALD-LEVEL>  <OUTPUT-DIRECTORY-PATH>
         (minimal reasonable hald-level is 8, recommended for production - 16)

   - If, as in the sample output above - you see "* Usage: …" somehere near the bottom, Anahald succeeded to start
   - Otherwise please examine the error messages and fix accordingly

2. Check the main Anahald functionality by requesting a tiny LUT (HALD-level of 2):

   - On Linux - in BASH - type:
     cd <Anahald-Root>
     bin/anahald_lut_make.sh CFG/ahg_oleg_cp.ini 2 TMP
   - On Windows - in DOS-CMD - type:
     cd <Anahald-Root>
     bin\anahald_lut_make.bat CFG\ahg_oleg_cp.ini 2 TMP
   - (The sample output is intentionally truncated to concentrate on the error)

       $ bin/anahald_lut_make.sh CFG/ahg_oleg_cp.ini  2  TMP
       ... Begin loading TCL code ...
          ...
       ... Done  loading TCL code ...
       ============ Running Anaglyph HALD Generator under SH/BASH =============

       Config file: 'CFG/ahg_oleg_cp.ini',  HALD-level: 2,  output-directory: 'TMP'
        ...
       -I- Runtime of generating HALD-02 with 48 of 64 color(s) replaced is 0 second(s)
       -E- Failed executing command: 'magick  TMP/hald__ahg_oleg_cp__02.TXT  -depth 8  -compress LZW TMP/hald__ahg_oleg_cp__02.TIF'.
       -E- Failed converting HALD text file 'TMP/hald__ahg_oleg_cp__02.TXT' into image 'TMP/hald__ahg_oleg_cp__02.TIF': couldn't execute "magick": no such file or directory!

       ======== Finished running Anaglyph HALD Generator under SH/BASH ========

   The above console output from the 1st attempt to generate a LUT hints that Anahald tried to invoke ImageMagick's "magick" utility but failed to. The reason - ImageMagick on this computer has it under the historical name "convert".

   - The solution is to redirect the calls to "convert" - see "For ImageMagick - if on Linux" or "For ImageMagick - if on Windows". Doing just that leads to a flawless invocation.

   - Sample output from the 1st successful run of Anahald LUT generation:

         $ bin/anahald_lut_make.sh CFG/ahg_oleg_cp.ini  2  TMP
         ...
         -I- Imagemagick convert/magick utility will be called as '/home/oleg/ANY/GitWork/AnaHald/bin/convert.sh'
         ...
         ============ Running Anaglyph HALD Generator under SH/BASH =============
         ...
         Config file: 'CFG/ahg_oleg_cp.ini',  HALD-level: 2,  output-directory: 'TMP'

         -I- Enough disk space available for HALD file of level 2 in format TIF under directory 'TMP'
         -I- Building LUT for 64 color(s); progress report occurs once per 8 color(s)
         -I- ... so far processed 9 color(s) out of 64 in HALD-02 ...

         -I- ... so far processed 57 color(s) out of 64 in HALD-02 ...
         -I- Generated HALD-02 with 48 of 64 color(s) replaced; new text version saved in 'TMP/hald__ahg_oleg_cp__02.TXT'
         ...
         -I- Success converting HALD text file 'TMP/hald__ahg_oleg_cp__02.TXT' into image 'TMP/hald__ahg_oleg_cp__02.TIF'
         ...
         -I- Deleted temporary HALD-02 text file 'TMP/hald__ahg_oleg_cp__02.TXT'
         ...
         ======== Finished running Anaglyph HALD Generator under SH/BASH ========

   Comparison of identity HALD with the HALD made by anahald_lut_make command in 1.2

   Figure 1: Identity HALD (left) versus the HALD made by anahald_lut_make command in 1.2 (right)

   As the comparison above illustrates, Anahald not only finished the run, but created a CLUT that replaces saturated colors with similarly looking "relatives".

3. Check reading config files by Anahald - view all config files in a directory
   Anahald provides an utility to build summary tables for available Anahald configuration files, and here is how to verify it:

   - On Linux - in BASH - type:
     cd <Anahald-Root>
     bin/anahald_cfg_table.sh GLOB CFG "*.ini"
   - On Windows - in DOS-CMD - type:
     cd <Anahald-Root>
     bin\anahald_cfg_table.bat GLOB CFG "*.ini"
   - (note, glob patterns need double-quotes)
   - (The sample output intentionally omits the setup preamble and shows only the actual results)

       $ bin/anahald_cfg_table.sh GLOB CFG "*.ini"
       ...
       Config files' directory: 'CFG',  config files' name-pattern: '*.ini'

              -ID-|Green|MinBn|MaxRg|Smoot|PreSq|MinMi|PreIn|MaxBa
                  |ToBlu|dBala| bVal|hBndB|ueeze|norSc|flate|lance
                  |eBias|ncedM|     |alanc|Major|aleOp|Minor|dMajo
                  |MultW|ajorT|     |edOpt|ToFra| tion|ToFra|rToMa
                  |henMi|oMaxM|     |  ion|   ct|     |   ct|xMino
                  |  nor|inorR|     |     |     |     |     |rRati
                  |     | atio|     |     |     |     |     |    o
       ahg_oleg_sf| 0.85|  1.0|  255|    1| 1.00|    1| 0.50|  2.0
       ahg_oleg_cp| 0.97|  1.5|  255|    2| 0.80|    2|  1.0|  3.0
       ahg_oleg_ec|  1.0|  1.0|  255|    1| 0.90|    1|  1.0|  2.0
       ahg_oleg_gp|  1.0|  1.3|  255|    2| 0.90|    2|  1.0|  2.0
       ======== Finished collecting Anaglyph HALD Config summary under SH/BASH ========

   The sample output table above shows essential content of config files included with Anahald

   - In case error(s) appear instead of the table, their text should be descriptive enough to help with resolution.

   If your outcome matches the example, congratulations! … And enjoy your anaglyph photos becoming more colorful!

## Installing additional features

These are:

1. Automatic choice of sample HALD-LUT for an image
   - installation instructions are in Installing Anahald-Choice
2. GUI Viewer
   - no additional installation steps required

Oleg Kosyakovsky

Haifa, Israel

2024-2025