Anaglyph HALD Generator (Anahald) - Installation

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

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

(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
     │   ├── img_proc
     │   └── ok_utils
     └── Doc
         └── files
             └── css
     
     9 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.
     

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.

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!