README

   1 ========================
   2 ALE version 0.8.4 README
   3 ========================
   4
   5 This README discusses downloading, extraction, and compilation of ALE.
   6 Documentation about the command-line interface and program options can be found
   7 on the ALE web site; see the end of the README for relevant URLs.
   8
   9 Subsections:
  10
  11         + Windows Binaries
  12                 - URLs
  13                 - Extraction and Use
  14         + Compiling from source
  15                 - URLs
  16                 - Build prerequisites
  17                 - Extraction and Building
  18         + Compilation options
  19                 - ImageMagick Support
  20                 - Color Data Precision
  21                 - Coordinate Data Precision
  22                 - FFTW Support
  23                 - POSIX Support
  24                 - IOCTL Support
  25                 - Assertions
  26         + Further Documentation
  27         + URLs
  28         + Mailing List
  29
  30
  31 Windows Binaries
  32 ================
  33
  34
  35 URLs
  36 ----
  37
  38 http://auricle.dyndns.org/ALE/download/ale-0_8_4-win32.zip
  39
  40
  41 Extraction and Use
  42 ------------------
  43
  44 The zip file available at the above URL is an archive containing the ALE
  45 executable; a zip archival utility can be used to extract the executable from
  46 the archive.
  47
  48 Once extracted, since ALE is a command-line program, it may be necessary to
  49 open a command prompt window to use ALE successfully.  For more information
  50 about command-line usage and options, see the User Manual at the URL given at
  51 the bottom of this file.
  52
  53 Note that the Windows binaries available on the ALE website read and write only
  54 PPM-formatted image files.  However, separate conversion tools can be used to
  55 convert between other formats and PPM (e.g. ImageMagick's command-line
  56 utilities, available from http://www.imagemagick.org/ ).
  57
  58
  59 Compiling from source
  60 =====================
  61
  62
  63 URLs
  64 ----
  65
  66 http://auricle.dyndns.org/ALE/download/ale-0.8.4.tar.gz
  67
  68
  69 Build prerequisites
  70 -------------------
  71
  72 GCC version 3.2.3 with C++ support and GNU Make 3.80 are known to build ALE
  73 successfully.  Older versions of GCC may fail to compile some versions of ALE.
  74
  75
  76 Extraction and Installation
  77 ---------------------------
  78
  79 Download the source archive file from the URL indicated above, and invoke:
  80
  81         tar xzf ale-0.8.4.tar.gz
  82         cd ale-0.8.4
  83         make [OPTIONS]
  84
  85 where the text '[OPTIONS]' is replaced by zero or more of the compilation
  86 options listed below.  (The makefile may need to be modified for successful
  87 compilation on Windows systems.)
  88
  89
  90 Compilation options
  91 ===================
  92
  93 All compilation options are of the form OPTION=VALUE.  Default options are
  94 denoted by '*'.
  95
  96
  97 ImageMagick Support
  98 -------------------
  99
 100 Enabling ImageMagick support allows ALE to make use of the file-handling
 101 capabilities of ImageMagick ( http://imagemagick.org/ ).  This includes reading
 102 and writing a variety of file formats, including, among many others, PNG and
 103 JPEG (two formats commonly used in web publishing) as well as common
 104 interchange formats such as PPM and TIFF.  ImageMagick 6.0.6 is known to work
 105 with this version of ALE; certain older versions of ImageMagick may cause
 106 compile, link, or runtime errors.
 107
 108 IMAGEMAGICK=0 *        Disable ImageMagick support.
 109 IMAGEMAGICK=1          Enable ImageMagick support.
 110
 111
 112 Color Data Precision
 113 --------------------
 114
 115 ALE's internal data structures store each color channel within a pixel as
 116 floating-point data; similarly, arithmetic operations on color channels are
 117 performed in floating point.  The three available data-type configurations are
 118 listed below, with typical data sizes indicated in parentheses.  Note that the
 119 required runtime for COLORS=HALF configurations can be several times that of
 120 COLORS=SINGLE configurations.
 121
 122                        Storage                Arithmetic
 123                        -------------------    -------------------
 124 COLORS=SINGLE *        C++ float  (32-bit)    C++ float  (32-bit)
 125 COLORS=DOUBLE          C++ double (64-bit)    C++ double (64-bit)
 126 COLORS=HALF            Custom     (16-bit)    C++ float  (32-bit)
 127
 128 Note: COLORS=HALF can be very computationally expensive.
 129
 130
 131 Coordinate Data Precision
 132 -------------------------
 133
 134 In general, coordinate transformations used by ALE produce results outside of
 135 the set of integers; hence, coordinates are treated as floating-point data.
 136 The two available data-type configurations are listed below, with typical data
 137 sizes indicated in parentheses.
 138
 139 COORDINATES=SINGLE *   C++ float  (32-bit)
 140 COORDINATES=DOUBLE     C++ double (64-bit)
 141
 142
 143 FFTW Support
 144 ------------
 145
 146 For Irani-Peleg rendering, ALE computes a discrete Fourier transform of the
 147 estimated point-spread function.  Since the area in which an estimated
 148 point-spread function is non-zero is usually much smaller than the size of an
 149 input frame, the efficiency of this operation is unlikely to be important.
 150 Hence, ALE uses a relatively inefficient built-in transform by default.  To use
 151 FFTW instead of the built-in transform, specify FFTW=1.  This option requires
 152 FFTW version 3 libraries and header files to be installed.  For more details on
 153 FFTW, see http://fftw.org/
 154
 155 This build option is required in order to use the --fl option.
 156
 157 FFTW=0 *               Use a built-in discrete Fourier transform.
 158 FFTW=1                 Use the FFTW3 discrete Fourier transform.
 159
 160
 161 POSIX Support
 162 -------------
 163
 164 This build option is required in order to use the --wmx option.  If
 165 POSIX=1 is specified, it is expected that fork() and execlp() calls
 166 are available.
 167
 168 POSIX=0                Do not use POSIX fork() and execlp()
 169 POSIX=1 *              Use POSIX fork() and execlp()
 170
 171
 172 IOCTL Support
 173 -------------
 174
 175 This build option is required to obtain additional output from --ui=tty.  If
 176 TIOCGWINSZ is not defined in <sys/ioctl.h>, however, additional output will not
 177 be provided even if IOCTL=1 is specified at build time.
 178
 179 IOCTL=0 *               Do not use ioctl()
 180 IOCTL=1                 Use ioctl()
 181
 182
 183 Assertions
 184 ----------
 185
 186 Finding bugs within ALE, or within custom modifications to ALE, can be
 187 simplified by enabling run-time assertions.  These checks enforce conditions
 188 believed to be necessary or desirable for correct program operation.  If a
 189 condition is not satisfied, ALE will abort and display a message indicating the
 190 failed assertion.
 191
 192 DEBUG=0 *              Disable assertions.
 193 DEBUG=1                Enable assertions.
 194
 195
 196 Further Documentation
 197 =====================
 198
 199 For information about command-line usage and program options, see the on-line
 200 user manual, available at the URL indicated in the next section.  A technical
 201 description of ALE operation is also available.
 202
 203
 204 URLs
 205 ====
 206
 207 Home Page               http://auricle.dyndns.org/ALE/
 208 User Manual             http://auricle.dyndns.org/ALE/user/
 209 Technical Description   http://auricle.dyndns.org/ALE/tech/
 210 Mailing list archive    http://ventricle.dyndns.org/pipermail/ale/
 211
 212
 213 Mailing List
 214 ============
 215
 216 Bug reports, feature requests, patch and release announcements, and related
 217 discussion can be sent to ale@ventricle.dyndns.org.  Archives of past postings
 218 and subscription information are available at the URLs indicated below.
 219
 220 Posting address         ale@ventricle.dyndns.org
 221 Subscription info       http://ventricle.dyndns.org/cgi-bin/mailman/listinfo/ale
 222 Archives                http://ventricle.dyndns.org/pipermail/ale/