MkSIS - Singe Image Stererograms

MkSIS is an integrated set of programs for creating high-quality Single Image Stereogram (SIS) images.

Download

Web page: https://thinairarts.com/stereogram.html

Fossil repo: https://thinairarts.com/fossil/MkSIS

Documentation: https://thinairarts.com/fossil/MkSIS/wiki/documentation

Background

A Single Image Stereogram or SIS is a self-contained 3D image. Very popular back in the 90's (the Magic Eye phenomenon), SIS attracted a lot of attention from programmers. While that interest has waned considerably a number of programs for generating SIS images are currently maintained. Some are proprietary, while available open source options give IMO less than optimum results.

A SIS is generated from a depthmap and a texture file. Depthmaps are usually monochrome images, white/black representing the near/far plans respectively. The texture image provides pixels that are shifted left or right to give different angles of view for left and right eyes according to the distance encoded by the depthmap. In that way it looks 3D.

More than 6 months back I wanted to create a SIS program that produced "artist-quality" images. A common issue with SIS generators is "artifacting", where spurious lines mar the image and interfere with the 3D effect. A goal of MkSIS was producing near artifact-free output, definitely a contributor to image quality.

Tcl isn't an ideal language for implementing SIS algorithms given the large amount of data and the math-intensive computations involved. Playing to its strengths, TclTk is highly adapted to creating GUI frontends that optimize interaction with (C,C++,etc.)-based backend programs doing the computational heavy lifting. Other approaches are possible, for example, creating a unified app via the tcl C interface, a challenging project to accomplish. Implementing the frontend/backend paradigm would be difficult enough, so it was the approach taken.

Description

Currently MkSIS runs on Windows but porting to Linux, BSD, etc., shouldn't be difficult. MkSIS consists of 3 executables (and support files):

• the GUI (*.tcl files and statically compiled wish86s.exe)
• backend command-line SIS generator written in C (sis-backend.exe)
• utility for "silently" starting GUI, written in C (runner.exe)

A project goal was ease of use for non-programmers. That includes not needing to install TclTk. Tclkit or freewrap could accommodate the TclTk part, but the backend executable still must be found externally as it doesn't run from VFS. Alternatively bundling the program components in a properly populated directory canaccomplish the goal, that is, running as an "app" without requiring external resources (other than OS itself).

The latter is possible because on startup, if the environment variable TCL_LIBRARY exists, tcl uses the path in the variable as its init directory instead of the compiled-in location. So if init directories are copied to an arbitrary directory, setting "TCL_LIBRARY=/current_dir/tcl8.6" allows "wish ..." to run without having tcltk otherwise installed. Such app directories can be located anywhere in the user-accessible file system.

Components

Frontend GUI

The GUI is constructed primarily in gui-main.tcl. Entry widgets and spinbuttons hold parameters that will be passed to sis-backend.exe. The documentation describes in detail the interface and its usage.

gui-image.tcl extends mksis namespace to popup the SIS result. The image size can be increased/decreased by pressing +/- keys and dismissed by return, escape or a mouse button press.

gui-reopen.tcl sets up an interface to the image info log saved by sis-backend.exe. This is useful for resetting parameters of a formerly produced image. This allows the prior SIS image to be reproduced exactly or the parameters modified as desired.

Backend program

The backend program is a complete standalone command-line SIS generator. It's statically compiled in the msys2 environment. Image DLLs are therefore not required at runtime. The executable "mksis.exe" is installed to /usr/local/bin (which should be added to the Windows exe PATH), as well as captured in MkSIS.zip as 'sis-backend.exe' with the same core functionality. Command-line switches correspond to parameters noted above. To use in standalone mode, run as mksis.exe at a command prompt. With no arguments a help message is printed.

A major source of artifacts derives from the fact that pixels are atomic and pixel placement must round up or down when fractional values are computed. Also in areas where depthmaps have steep gradients, distance between steps is large which inevitably leaves gaps. Mksis.exe greatly reduces artifacts by applying a buffer "look-behind" algorithm that fills in pixels missed during depth-based assignment.

Input/output image formats are tif, png and jpg. Depthmaps can be grayscale or RGB/24bit. Texture files, and output SIS images are RGB/24bit. Output image size will be the same as the depthmap dimensions. Texture pixels are tiled vertically and horizontally if the image isn't large enough to fill areas in the output image.

Runner utility

The runner.exe utility adds variable (TCL_LIBRARY="<current directory>/tcl8.6") to the environment and starts the target program. It reads a config file (runner.cfg) to extract target program name (wishXX or tclshXX) and arguments.

Runner replaces VB scripts or other Scripting Host methods of calling programs silently, that is, without console "flashing" seen when using .bat or .ps1 files to start programs. (Runner is compiled in msys2 as a -mwindows program, so strictly speaking not a console utility. However Runner doesn't open a window for itself, though it will show a Windows messagebox to notify users of errors.)

More Info

Please see web page and Fossil repository for in-depth information.