ui/help.h

   1 // Copyright 2002, 2003, 2004 David Hilvert <dhilvert@auricle.dyndns.org>,
   2 //                                          <dhilvert@ugcs.caltech.edu>
   3
   4 /*  This file is part of the Anti-Lamenessing Engine.
   5
   6     The Anti-Lamenessing Engine is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation; either version 3 of the License, or
   9     (at your option) any later version.
  10
  11     The Anti-Lamenessing Engine is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14     GNU General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with the Anti-Lamenessing Engine; if not, write to the Free Software
  18     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19 */
  20
  21 /*
  22  * Help messages
  23  */
  24
  25 #define BETWEEN_SECTIONS "\n"
  26 #define HEADER_SPACE ""
  27
  28 class help {
  29 private:
  30         const char *package;
  31         const char *version;
  32         const char *invocation;
  33         FILE *help_stream;
  34
  35         /*
  36          * Stars
  37          *
  38          * This function produces a line of stars for banner output.
  39          */
  40         void stars(unsigned int n) {
  41                 for (unsigned int i = 0; i < n; i++) {
  42                         fprintf(help_stream, "*");
  43                 }
  44                 fprintf(help_stream, "\n");
  45         }
  46
  47
  48         /*
  49          * Banner
  50          *
  51          * This function aids in locating the start of help output.
  52          */
  53         void banner(const char *name) {
  54                 const char *package_banner = " Help Text, version ";
  55                 const char *section_banner = "Section: ";
  56
  57                 int plen = strlen(package) + strlen(package_banner) + strlen(version);
  58                 int slen = strlen(section_banner) + strlen(name);
  59                 int len = (plen > slen) ? plen : slen;
  60
  61                 fprintf(help_stream, BETWEEN_SECTIONS);
  62                 stars(len);
  63                 fprintf(help_stream, "%s%s%s\n", package, package_banner, version);
  64                 fprintf(help_stream, "%s%s\n", section_banner, name);
  65                 stars(len);
  66         }
  67
  68 public:
  69         help(const char *package, const char *invocation, const char *version) {
  70                 this->invocation = invocation;
  71                 this->package = package;
  72                 this->version = version;
  73                 this->help_stream = stdout;
  74         }
  75
  76         /*
  77          * Describe how to use this program
  78          */
  79         void usage() {
  80                 banner("Usage");
  81                 fprintf(help_stream,
  82                         BETWEEN_SECTIONS
  83                         "Usage: %s [<options>] <original-frame> [<supplemental-frame> ...] <output-file>\n"
  84                         "   or: %s [<help option> ...]\n"
  85                         "   or: %s --version\n"
  86                         BETWEEN_SECTIONS
  87                         "Help options:\n"
  88                         HEADER_SPACE
  89                         "--hu              Usage (this message).\n"
  90                         "--hf              Image files.\n"
  91                         "--he              Exclusion regions.\n"
  92                         "--ha              Alignment (not exposure-related).\n"
  93                         "--hr              Rendering (not exposure-related).\n"
  94                         "--hx              Exposure.\n"
  95                         "--ht              Transformation data files.\n"
  96                         "--hc              Control points.\n"
  97                         "--hl              Filtering (PSFs, rendering chains).\n"
  98                         "--hd              Devices.\n"
  99                         "--hi              User Interfaces.\n"
 100                         "--hp              Process details.\n"
 101                         "--hs              Argument scope (Experimental).\n"
 102                         "--hv              Video stream processing (Experimental).\n"
 103                         "--h3              3D Modeling (Experimental).\n"
 104                         "--hz              Undocumented options.\n"
 105                         "--hA              Concatenate all help pages.\n"
 106                         "\n",
 107                         invocation, invocation, invocation);
 108         }
 109
 110         void defaults() {
 111                 banner("Defaults");
 112                 fprintf(help_stream,
 113                         BETWEEN_SECTIONS
 114                         "Default settings:\n"
 115                         HEADER_SPACE
 116                         "--q* options are no longer recognized.\n"
 117                         "\n"
 118                        );
 119         }
 120
 121         void file() {
 122                 banner("File");
 123                 fprintf(help_stream,
 124                         BETWEEN_SECTIONS
 125                         "Cache options:\n"
 126                         HEADER_SPACE
 127                         "--cache <size>    Cache up to <size> megabytes of image data.   (256 is default)\n"
 128                         BETWEEN_SECTIONS
 129                         "Bit depth options:\n"
 130                         HEADER_SPACE
 131                         "--8bpc            Write 8 bit per channel output\n"
 132                         "--16bpc           Write 16 bit per channel output [default]\n"
 133                         BETWEEN_SECTIONS
 134                         "Output format options:\n"
 135                         HEADER_SPACE
 136 #ifdef USE_MAGICK
 137                         "--auto            Determine output file type automatically [default]\n"
 138                         "--raw             Write raw PPM output\n"
 139                         "--plain           Write plain PPM output\n"
 140 #else
 141                         "--raw             Write raw PPM output [default]\n"
 142                         "--plain           Write plain PPM output\n"
 143 #endif
 144                         BETWEEN_SECTIONS
 145                         "Incremental output:\n"
 146                         HEADER_SPACE
 147                         "--inc             Produce rough incremental output.\n"
 148                         "--no-inc          Don't produce any incremental output.  [default]\n"
 149
 150                         BETWEEN_SECTIONS
 151                         "Undefined values:\n"
 152                         HEADER_SPACE
 153                         "--def-nn <R>      Use nearest-neighbor defined values within\n"
 154                         "                  radius <R>, zero outside.  Default radius is 0.\n"
 155                         "\n"
 156                        );
 157         }
 158         void alignment() {
 159                 banner("Alignment");
 160                 fprintf(help_stream,
 161                         BETWEEN_SECTIONS
 162                         "Alignment channel options:\n"
 163                         HEADER_SPACE
 164                         "--align-all       Align images using all color channels\n"
 165                         "--align-green     Align images using the green channel\n"
 166                         "--align-sum       Align images using a sum of channels [default]\n"
 167                         BETWEEN_SECTIONS
 168                         "Transformation options:\n"
 169                         HEADER_SPACE
 170                         "--translation     Only adjust the position of images\n"
 171                         "--euclidean       Adjust the position and orientation of images [default]\n"
 172                         "--projective      Use projective transformations.  Best quality, but slow.\n"
 173                         BETWEEN_SECTIONS
 174                         "Alignment following:\n"
 175                         HEADER_SPACE
 176                         "--follow          Frames align closely with their predecessor.  [default]\n"
 177                         "--identity        Frames align closely with the original frame.\n"
 178                         BETWEEN_SECTIONS
 179                         "Alignment failure:\n"
 180                         HEADER_SPACE
 181                         "--fail-optimal    Frames beneath threshold are aligned optimally.  [default]\n"
 182                         "--fail-default    Frames beneath threshold keep their default alignment.\n"
 183                         BETWEEN_SECTIONS
 184                         "Transformation file operations:\n"
 185                         HEADER_SPACE
 186                         "--trans-load <x>  Load initial transformation settings from file <x>\n"
 187                         "--trans-save <x>  Save final transformation data in file <x>\n"
 188                         BETWEEN_SECTIONS
 189                         "Tunable parameters:\n"
 190                         HEADER_SPACE
 191                         "--metric=x        Set the alignment error metric exponent.       (2 is default)\n"
 192                         "--threshold=x     Minimum match percentage; -1 disables check.  (-1 is default)\n"
 193                         "--perturb-upper=x Perturbation upper bound pixels/arclength    (14%% is default)\n"
 194                         "                     ('x%%' uses a fraction of the smallest image dimension.)\n"
 195                         "--perturb-lower=x Perturbation lower bound pixels/arclength   (.125 is default)\n"
 196                         "                     ('x%%' uses a fraction of the smallest image dimension.)\n"
 197                         "--rot-upper=x     Rotation-specific upper bound in degrees    (32.0 is default)\n"
 198                         "--bda-mult=x      Barrel distortion adjustment multiplier      (2.0 is default)\n"
 199                         "--bda-rate=x      Barrel distortion rate of change maximum     (8.0 is default)\n"
 200                         "--lod-preferred=x Preferred LOD scale is (2^floor(x))/perturb)  (-3 is default)\n"
 201                         "--min-dimension=x Minimum dimension for reduced LOD is x        (10 is default)\n"
 202                         "--mc <x>          Statically sample ~x%% of available pixels     (30 is default)\n"
 203                         BETWEEN_SECTIONS
 204                         "Certainty-weighted alignment:\n"
 205                         HEADER_SPACE
 206                         "--cw              Weight alignment error by certainty.\n"
 207                         "--no-cw           Don't weight alignment error by certainty. [default]\n"
 208                         BETWEEN_SECTIONS
 209                         "Alignment weight maps:\n"
 210                         HEADER_SPACE
 211                         "--wm <f> <x> <y>  Use weight map image <f> at offset (<x>, <y>)\n"
 212                         BETWEEN_SECTIONS
 213                         "Frequency-weighted alignment:\n"
 214                         HEADER_SPACE
 215                         "--fl <h> <v> <a>  High-pass filters: horizontal <h>, vertical <v>, average <a>.\n"
 216                         "                     Values should fall between 0 (pass all) and 1 (pass none).\n"
 217 #ifndef USE_FFTW
 218                         "\n"
 219                         "                     NOTE: since this build of ALE does not link with FFTW,\n"
 220                         "                           this option is not supported.  To use this option,\n"
 221                         "                           first re-build with FFTW support.\n"
 222                         "\n"
 223 #endif
 224                         "--flshow <o>      Write high-pass filtered data to file <o>.\n"
 225                         BETWEEN_SECTIONS
 226                         "Algorithmic alignment weighting:\n"
 227                         HEADER_SPACE
 228                         "--wmx <e> <r> <d> Write reference <r>, definition <d>, execute `<e> <f> <d>`,\n"
 229                         "                  read weights <r> back.\n"
 230 #ifndef USE_UNIX
 231                         "\n"
 232                         "                     NOTE: since this build was not configured with\n"
 233                         "                           support for --wmx, this option is not supported.\n"
 234                         "                           To use this option, re-build with support for --wmx.\n"
 235 #endif
 236                         BETWEEN_SECTIONS
 237                         "Perturbation Type [experimental]:\n"
 238                         HEADER_SPACE
 239                         "--perturb-output  Apply perturbations in output image coordinates. [default]\n"
 240                         "--perturb-source  Apply perturbations in source image coordinates.\n"
 241                         BETWEEN_SECTIONS
 242                         "Global searching:\n"
 243                         HEADER_SPACE
 244                         "--gs <type>       Set global search to <type>, one of:\n"
 245                         "                     local     Local alignment only\n"
 246                         "                     inner     Alignment reference image inner region\n"
 247                         "                     outer     Alignment reference image outer region\n"
 248                         "                     all       Union of inner and outer\n"
 249                         "                     central   inner if below threshold or better; else, outer.\n"
 250                         "                     defaults  'all' if default, 'local' otherwise.  [default]\n"
 251                         "                     points    Align by control points.  Ignores gs-mo.\n"
 252                         "--gs-mo <x>       Set <x> pixel min. overlap for global search.   (67%% default)\n"
 253                         "                     ('x%%' uses a fraction of the total pixel count.)\n"
 254                         BETWEEN_SECTIONS
 255                         "Multi-alignment:\n"
 256                         HEADER_SPACE
 257                         "--md <x>          Set element minimum dimension x; 0 disables. (100 is default)\n"
 258                         "--ma-cert <x>     Set mean certainty lower bound.             (0.01 is default)\n"
 259                         "--mi <x>          Require error improvement fraction <x>.        (0 is default)\n"
 260                         "\n"
 261                        );
 262         }
 263
 264         void rendering() {
 265                 banner("Rendering");
 266                 fprintf(help_stream,
 267                         BETWEEN_SECTIONS
 268                         "Mimicking ALE 0.6.0 merging and drizzling (see --hl for details):\n"
 269                         HEADER_SPACE
 270                         "   --dchain triangle:2     approximates merging.\n"
 271                         "   --dchain fine:box:1     approximates drizzling.\n"
 272                         BETWEEN_SECTIONS
 273                         "Image extents:\n"
 274                         HEADER_SPACE
 275                         "--extend          Increase image extents to accommodate all pixel data.\n"
 276                         "--no-extend       Don't increase extents; crop to original frame. [default]\n"
 277                         BETWEEN_SECTIONS
 278                         "Tunable parameters:\n"
 279                         HEADER_SPACE
 280                         "--scale=x         Scale images by the factor x, where x > 0.     (1 is default)\n"
 281                         "--threshold=x     Min. match threshold; a perfect match is 100.  (0 is default)\n"
 282                         BETWEEN_SECTIONS
 283                         "Irani-Peleg iterative solver:\n"
 284                         HEADER_SPACE
 285 #define FIXED16 4
 286 #if ALE_COLORS == FIXED16
 287                         "--ips <i>         Run <i> iterations.                            (0 is default)\n"
 288 #else
 289                         "--ips <i>         Run <i> iterations.                            (1 is default)\n"
 290 #endif
 291 #undef FIXED16
 292                         "--ip-mean         Use the mean correction [default]\n"
 293                         "--ip-median       Use the median correction\n"
 294                         "--ip-wl <x>       Use weight limit <x>\n"
 295                         "--ip-nowl         Use no weight limit [default]\n"
 296 #if 0
 297                         BETWEEN_SECTIONS
 298                         "Unsharp Mask (was 'High-frequency Enhancement'):\n"
 299                         HEADER_SPACE
 300                         "--usm <m>         Apply an unsharp mask with multiplier <m>.\n"
 301                         "                     (See also --device, --nlpsf, and --lpsf.)\n"
 302 #endif
 303                         BETWEEN_SECTIONS
 304                         "Bayer pattern:\n"
 305                         HEADER_SPACE
 306                         "--bayer <b>       Set the Bayer pattern to <b>, one of:\n"
 307                         "                    (clockwise from top left pixel)\n"
 308                         "                      rgbg      Red-green-blue-green\n"
 309                         "                      gbgr      Green-blue-green-red\n"
 310                         "                      grgb      Green-red-green-blue\n"
 311                         "                      bgrg      Blue-green-red-green\n"
 312                         "                      none      RGB-RGB-RGB-RGB\n"
 313                         "                  Default is none or device-specific.\n"
 314                         BETWEEN_SECTIONS
 315                         "Color adjustment:\n"
 316                         HEADER_SPACE
 317                         "--exp-mult=c,r,b   Adjust all channels by <c>, red by <r>, and blue by <b>.\n"
 318                         "\n"
 319                 );
 320         }
 321         void filtering() {
 322                 banner("Filtering");
 323                 fprintf(help_stream,
 324                         BETWEEN_SECTIONS
 325                         "Point-spread functions (used with --ips; see --hr):\n"
 326                         HEADER_SPACE
 327                         "--lpsf <p>        Set linear colorspace point-spread function to <p>\n"
 328                         "--nlpsf <p>       Set non-linear colorspace point-spread function to <p>\n"
 329                         "                     Available point-spread functions:\n"
 330                         "                        box=<diameter>\n"
 331                         "                        circle=<diameter>\n"
 332                         "                        gauss=<diameter of one std. deviation>\n"
 333                         "                        stdin\n"
 334                         "                        stdin_vg\n"
 335                         "                        <p>+<p> (summation)\n"
 336                         "                        <p>^<p> (convolution)\n"
 337                         "                        <n>*<p> (multiplication by a scalar <n>)\n"
 338                         "                     Default lpsf is either 'box=1.0' or device-specific.\n"
 339                         "                     Default nlpsf is either disabled or device-specific.\n"
 340                         BETWEEN_SECTIONS
 341                         "Rendering chains:\n"
 342                         HEADER_SPACE
 343                         "--wt <w>          Set weight threshold for defined pixels (default is 0.0001).\n"
 344                         "--dchain <g>      Use chain <g> to render the default output.\n"
 345                         "--ochain <g> <o>  Use chain <g> to render output file <o>.\n"
 346                         "--achain <g>      Use chain <g> to render the alignment reference image.\n"
 347                         "--afilter <s>     Use SSF <s> to interpolate points in alignment.\n"
 348                         "--3d-chain <g>    Use chain <g> by default to render 3d output.\n"
 349                         "                  Example chains:\n"
 350                         "                     triangle:2                   ALE 0.6.0 merging (roughly)\n"
 351                         "                     fine:box:1                   Drizzling (roughly)\n"
 352                         "                     fine:sinc*lanc:8             High-frequency preservation\n"
 353                         "                     last:nex:sinc*lanc:8         Useful for video stabilization\n"
 354                         "                     fine:box:1,triangle:2        Multi-resolution rendering\n"
 355                         "                     fine:sinc*lanc:8,sinc*lanc:8 Multi-resolution rendering\n"
 356                         "                     auto:box:1,fine:box:1,box:1  Range-resolution rendering.\n"
 357                         "                  More precisely, chains <g> are one of:\n"
 358                         "                     <g1>,<g2>      Chain <g1> where defined; <g2> elsewhere.\n"
 359                         "                     <i>            Use rendering invariant <i>.\n"
 360                         "                  Rendering invariants <i> are:\n"
 361                         "                     avg:<e>        Avg. (mean) value using SSFE <e>.\n"
 362                         "                     avgf:<x>:<e>   Avg. first up to weight <x> using SSFE <e>.\n"
 363                         "                     first:<e>      First defined value using SSFE <e>.\n"
 364                         "                     last:<e>       Last defined value using SSFE <e>.\n"
 365                         "                     max:<e>        Maximum defined value using SSFE <e>.\n"
 366                         "                     min:<e>        Minimum defined value using SSFE <e>.\n"
 367                         "                     median:<e>     Median value using SSFE <e>.\n"
 368                         "                     <e>            Same as avg:<e>.\n"
 369                         "                  Scaled sampling filters with exclusion (SSFE) <e> are:\n"
 370                         "                     ex:<s>         Use SSF <s>; honor exclusion regions.\n"
 371                         "                     nex:<s>        Use SSF <s>; don't honor exclusion regions.\n"
 372                         "                     <s>            Same as ex:<s>\n"
 373                         "                  Scaled sampling filters (SSF) <s> are:\n"
 374                         "                     auto:<f>       filter <f> from chain suffix resolutions.\n"
 375                         "                     fine:<f>       filter <f> at output image resolution.\n"
 376                         "                     coarse:<f>     filter <f> at resolution MIN(in, out).\n"
 377                         "                     <f>            Same as coarse:<f>.\n"
 378                         "                  Sampling filters <f> are:\n"
 379                         "                     sinc           Sinc filter. (very large diameter)\n"
 380                         "                     lanc:<x>       Lanczos, diameter <x>.\n"
 381                         "                     triangle:<x>   Triangle, diameter <x>.\n"
 382                         "                     box:<x>        Box, diameter <x>.\n"
 383                         "                     gauss:<x>      Gaussian, standard deviation <x>.\n"
 384                         "                     zero           Zero function.\n"
 385                         "                     <f>*<f>        Pointwise multiplication (windowing).\n"
 386                         "                  Defaults:\n"
 387                         "                     dchain         auto:triangle:2,fine:box:1,triangle:2\n"
 388                         "                     3d-chain       fine:triangle:2,fine:gauss:0.75,triangle:2\n"
 389                         "                     achain         triangle:2\n"
 390                         "                     afilter        internal (approximates triangle:2)\n"
 391                         "\n"
 392                         );
 393         }
 394         void device() {
 395                 banner("Device");
 396                 fprintf(help_stream,
 397                         BETWEEN_SECTIONS
 398                         "Device (may set PSF, Bayer pattern, exposure, and view angle):\n"
 399                         HEADER_SPACE
 400                         "--device <d>      Set the capture device to <d>.\n"
 401                         "                     Available devices (* expect linear inputs):\n"
 402                         "                        canon_300d *\n"
 403                         "                        canon_300d+50mm_1.4 *\n"
 404                         "                        canon_300d+50mm_1.4@1.4 *\n"
 405                         "                        canon_300d+50mm_1.8 *\n"
 406                         "                        canon_300d+85mm_1.8 *\n"
 407                         "                        nikon_d50 *\n"
 408                         "                        ov7620 *\n"
 409                         "                        xvp610_320x240\n"
 410                         "                        xvp610_640x480\n"
 411                         "\n"
 412                        );
 413         }
 414         void exclusion() {
 415                 banner("Exclusion");
 416                 fprintf(help_stream,
 417                         BETWEEN_SECTIONS
 418                         "Rendering-coordinate exclusion regions:\n"
 419                         HEADER_SPACE
 420                         "--ex <args>       Exclude a specified volume.\n"
 421                         "                     <args> are space-delimited horizontal,\n"
 422                         "                     vertical, and frame limits:\n"
 423                         "                         <xmin> <xmax> <ymin> <ymax> <fmin> <fmax>\n"
 424                         "                     using unscaled rendering spatial coordinates.\n"
 425                         "--crop <args>     Exclude the spatial complement of an area over a\n"
 426                         "                  specified set of frames.  <args> are:\n"
 427                         "                         <xmin> <xmax> <ymin> <ymax> <fmin> <fmax>\n"
 428                         "                     using unscaled rendering spatial coordinates.\n"
 429                         BETWEEN_SECTIONS
 430                         "Frame-coordinate exclusion regions:\n"
 431                         HEADER_SPACE
 432                         "--fex <args>      Exclude a specified volume.\n"
 433                         "                     <args> are space-delimited horizontal,\n"
 434                         "                     vertical, and frame limits:\n"
 435                         "                         <xmin> <xmax> <ymin> <ymax> <fmin> <fmax>\n"
 436                         "                     using unscaled frame spatial coordinates.\n"
 437                         "--fcrop <args>    Exclude the spatial complement of an area over a\n"
 438                         "                  specified set of frames.  <args> are:\n"
 439                         "                         <xmin> <xmax> <ymin> <ymax> <fmin> <fmax>\n"
 440                         "                     using unscaled frame spatial coordinates.\n"
 441                         "\n"
 442                        );
 443         }
 444         void exposure() {
 445                 banner("Exposure");
 446                 fprintf(help_stream,
 447                         BETWEEN_SECTIONS
 448                         "Certainty-weighted rendering:\n"
 449                         HEADER_SPACE
 450                         "--cx <x>          Render with certainty exponent <x>. (default is 1)\n"
 451                         "--no-cx           Render with uniform certainty.\n"
 452                         BETWEEN_SECTIONS
 453                         "Exposure registration:\n"
 454                         HEADER_SPACE
 455                         "--exp-register    Register exposure between frames.  [default]\n"
 456                         "--exp-noregister  Assume uniform exposure across all frames.\n"
 457                         "--exp-meta-only   Use only meta-data for registering exposure.\n"
 458                         BETWEEN_SECTIONS
 459                         "Range extension:\n"
 460                         HEADER_SPACE
 461                         "--exp-extend      Extend to include all calculated values.\n"
 462                         "--exp-noextend    Restrict to the original frame's range.  [default]\n"
 463                         BETWEEN_SECTIONS
 464                         "Exposure value meta-data:\n"
 465                         HEADER_SPACE
 466                         "--ev <x>          Set ISO 100 equivalent EV <x>.  (default is 0)\n"
 467                         "--black <x>       Set black level <x> as a fraction of saturation.  (default 0)\n"
 468                         "\n"
 469                        );
 470         }
 471         void tdf() {
 472                 banner("Transformation data files");
 473                 fprintf(help_stream,
 474                         BETWEEN_SECTIONS
 475                         "Version 2 syntax overview:\n"
 476                         HEADER_SPACE
 477                         "{version string}\n"
 478                         "{supplemental frame 1 transformation}\n"
 479                         "{supplemental frame 2 transformation}\n"
 480                         "...\n"
 481                         BETWEEN_SECTIONS
 482                         "Version 3 syntax overview:\n"
 483                         HEADER_SPACE
 484                         "{version string}\n"
 485                         "{original frame transformation}\n"
 486                         "{supplemental frame 1 transformation}\n"
 487                         "{supplemental frame 2 transformation}\n"
 488                         "...\n"
 489                         BETWEEN_SECTIONS
 490                         "Version string:\n"
 491                         HEADER_SPACE
 492                         "V <x>             Transformation data file version <x>.\n"
 493                         BETWEEN_SECTIONS
 494                         "Transformation overview:\n"
 495                         HEADER_SPACE
 496                         "{barrel/pincushion distortion command (optional; version 3 only)}\n"
 497                         "{projective, euclidean, or default command}\n"
 498                         BETWEEN_SECTIONS
 499                         "Barrel/pincushion distortion (version 3 only):\n"
 500                         HEADER_SPACE
 501                         "B <n> <coeff2> <coeff3> ... <coeff(n+1)>\n"
 502                         BETWEEN_SECTIONS
 503                         "Projective command:\n"
 504                         HEADER_SPACE
 505                         "P <xmax> <ymax> <tlx> <tly> <blx> <bly> <brx> <bry> <trx> <try>\n"
 506                         BETWEEN_SECTIONS
 507                         "Euclidean command:\n"
 508                         HEADER_SPACE
 509                         "E <xmax> <ymax> <xoffset> <yoffset> <angle>\n"
 510                         "\n"
 511                         BETWEEN_SECTIONS
 512                         "Comments:\n"
 513                         HEADER_SPACE
 514                         "# Lines beginning with '#' are comments.\n"
 515                         BETWEEN_SECTIONS
 516                         "Example:\n"
 517                         HEADER_SPACE
 518                         "# Version 3 transformation data file.\n"
 519                         "V 3\n"
 520                         "# Original frame, with barrel/pincushion distortion correction\n"
 521                         "B 3 0.1 0 -0.1\n"
 522                         "D\n"
 523                         "# Supplemental frame 1: shift a 640x480 image right by 100 pixels\n"
 524                         "E 640 480 100 0 0\n"
 525                         "\n"
 526                         );
 527         }
 528         void visp() {
 529                 banner("Video stream processing");
 530                 fprintf(help_stream,
 531                         BETWEEN_SECTIONS
 532                         "Video stream processing [Experimental]:\n"
 533                         HEADER_SPACE
 534                         "--visp <args>     Process a video sequence.\n"
 535                         "                     <args> are:\n"
 536                         "                         <chain> <stabilization-type> <prefix> <suffix>\n"
 537                         "                     <chain> is a rendering chain.  (see --hl)\n"
 538                         "                     <stabilization-type> is one of:\n"
 539                         "                         ma:<x>     Moving average over 2*<x> + 1 frames\n"
 540                         "                         sf:<x>     Stabilize to single frame number <x>\n"
 541                         "                         identity   Same as ma:0\n"
 542                         "                     <prefix> is an output file prefix\n"
 543                         "                     <suffix> is an output file suffix\n"
 544                         "--visp-scale=<x>  Use scale <x> for VISP output.  (default is 1.0)\n"
 545                         "--exshow          For single-invariant chains, show --ex regions dimmed.\n"
 546                         "\n");
 547         }
 548         void interface() {
 549                 banner("User Interface");
 550                 fprintf(help_stream,
 551                         BETWEEN_SECTIONS
 552                         "User Interfaces:\n"
 553                         HEADER_SPACE
 554                         "--ui=<type>       Set user interface to <type>, one of:\n"
 555                         "                     quiet\n"
 556                         "                     stream\n"
 557                         "                     tty [default]\n"
 558                         "                     log\n"
 559 #ifndef USE_IOCTL
 560                         "\n"
 561                         "                     NOTE: since ALE was compiled without terminal size check,\n"
 562                         "                     --ui=tty will behave identically to --ui=stream.\n"
 563                         "                     For additional output, recompile with terminal size check.\n"
 564 #endif
 565                         "\n");
 566         }
 567         void cp() {
 568                 banner("Control Points");
 569                 fprintf(help_stream,
 570                         BETWEEN_SECTIONS
 571                         "Control point files:\n"
 572                         HEADER_SPACE
 573                         "--cpf-load=<f>    Load control point data from file <f>\n"
 574                         "\n");
 575         }
 576         void d3() {
 577                 banner("3D Modeling [Experimental]");
 578                 fprintf(help_stream,
 579                         BETWEEN_SECTIONS
 580                         "Rendering:\n"
 581                         HEADER_SPACE
 582                         "--3dv <n> <o>     Render, to file <o>, colors as viewed from frame <n>.\n"
 583                         "--3dd <n> <o>     Render, to file <o>, depths as viewed from frame <n>.\n"
 584                         "--3dvp <args> <o> Render, to file <o>, colors viewed with projective <args>.\n"
 585                         "--3ddp <args> <o> Render, to file <o>, depths viewed with projective <args>.\n"
 586                         "                    <args> are W H V x y z P Y R:\n"
 587                         "                         W    image width.\n"
 588                         "                         H    image height.\n"
 589                         "                         V    camera view angle.\n"
 590                         "                         x    translation x component.\n"
 591                         "                         y    translation y component.\n"
 592                         "                         z    translation z component.\n"
 593                         "                         P    rotation around x-axis.\n"
 594                         "                         Y    rotation around y-axis.\n"
 595                         "                         R    rotation around z-axis.\n"
 596                         "--occ-norm        Normalize output with accumulated occupancy.        [default]\n"
 597                         "--occ-nonorm      Don't normalize output with accumulated occupancy.\n"
 598                         "--et <x>          Set encounter threshold <x> for defined pixels.[default is 0]\n"
 599                         "--3dpx <args>     Exclude a specified spatial volume following full-scene\n"
 600                         "                  reconstruction.  <args> are:\n"
 601                         "                         <xmin> <xmax> <ymin> <ymax> <zmin> <zmax>\n"
 602                         "--3d-filter       Use filtering for 3D color output.                  [default]\n"
 603                         "--3d-nofilter     Don't use filtering for 3D color output.\n"
 604                         "--3d-dmr <x>      Set radius for filtering median depth to <x>      [default 0]\n"
 605                         "--3d-fmr <x>      Set radius for filtering median diff to <x>       [default 0]\n"
 606                         "--focus <ft> <op> Create focus region with type <ft> and options <op>:\n"
 607                         "                     Focus type:\n"
 608                         "                        d <d>           focus at distance <d>\n"
 609                         "                        p <x> <y>       focus at point (x, y)\n"
 610                         "                     Space-separated options may include zero or more of:\n"
 611                         "                        ci=<ci>  camera index               [default 0]\n"
 612                         "                        fr=<fr>  focal range                [default 0]\n"
 613                         "                        ht=<ht>  horizontal tilt gradient   [default 0]\n"
 614                         "                        vt=<vt>  vertical tilt gradient     [default 0]\n"
 615                         "                        ap=<ap>  aperture diameter          [default 3]\n"
 616                         "                        sc=<sc>  sample count               [default 3]\n"
 617                         "                        sx=<sx>  start x coordinate      [default -Inf]\n"
 618                         "                        ex=<ex>  end x coordinate         [default Inf]\n"
 619                         "                        sy=<sy>  start y coordinate      [default -Inf]\n"
 620                         "                        ey=<ey>  end y coordinate         [default Inf]\n"
 621                         "                        sd=<sd>  start depth                [default 0]\n"
 622                         "                        ed=<ed>  end depth                [default Inf]\n"
 623                         "                        sr=<sr>  view sample randomization:\n"
 624                         "                            aperture  per aperture            [default]\n"
 625                         "                            pixel     per pixel\n"
 626                         "                        fs=<fs>  focal statistic, one of:\n"
 627                         "                            mean      mean of views           [default]\n"
 628                         "                            median    median of views\n"
 629                         "\n"
 630                         BETWEEN_SECTIONS
 631                         "Camera parameters:\n"
 632                         HEADER_SPACE
 633                         "--view-angle <x>  Set the initial diagonal view angle to <x> degrees.\n"
 634                         "                     (Default is 43.7 degrees or device-specific.)\n"
 635                         "--cpp-upper=<x>   Set upper bound <x> for camera parameter perturbation,\n"
 636                         "                  in pixels or degrees [default is 32]\n"
 637                         "--cpp-lower=<x>   Set lower bound <x> for camera parameter perturbation,\n"
 638                         "                  in pixels or degrees [default is 0.125]\n"
 639                         "--cpp-err-mean    Use RMS error to determine camera parameters.       [default]\n"
 640                         "--cpp-err-median  Use median error to determine camera parameters.               \n"
 641                         "--va-upper=<x>    View-angle perturbation upper bound in degrees   [default 32]\n"
 642                         "--st <x>          Set stereo threshold to <x> pixels.            [default is 4]\n"
 643                         "--vp-adjust       Adjust the view point                               [default]\n"
 644                         "--vp-noadjust     Do not adjust the view point\n"
 645                         "--vo-adjust       Adjust the view orientation                         [default]\n"
 646                         "--vo-noadjust     Do not adjust the view orientation\n"
 647                         BETWEEN_SECTIONS
 648                         "Transformation file operations:\n"
 649                         HEADER_SPACE
 650                         "--3d-trans-load=x Load initial transformation settings from file x\n"
 651                         "--3d-trans-save=x Save final transformation data in file x\n"
 652                         BETWEEN_SECTIONS
 653                         "Model rules:\n"
 654                         HEADER_SPACE
 655                         "--di-upper <x>    Decimate primary input resolution by at most 2^x  [default 0]\n"
 656                         "--di-lower <x>    Decimate input resolutions by at least 2^x     [default is 0]\n"
 657                         "--do-try <x>      Decimate output resolution by 2^x if possible  [default is 0]\n"
 658                         "--oc              Clip scene to output regions.\n"
 659                         "--no-oc           Do not clip scene to output regions.                [default]\n"
 660                         "--fc <x>          Set front-clip to <x> (0 < x < 1)              [default is 0]\n"
 661                         "--rc <x>          Set rear-clip to <x> (1 < x < inf)           [default is inf]\n"
 662                         "--fx <x>          Set falloff exponent to <x>                    [default is 1]\n"
 663                         "--tcem <x>        Set third-camera error multiplier to <x>       [default is 0]\n"
 664                         "--oui <x>         Set occupancy update iterations to <x>        [default is 10]\n"
 665                         "--pa <x>          Set pairwise ambiguity to <x>                  [default is 3]\n"
 666                         "--pc <type>       Set the type of pairwise comparisons:\n"
 667                         "                     auto     Determine comparisons automatically.    [default]\n"
 668                         "                     all      Perform all comparisons.\n"
 669                         "\n");
 670         }
 671         void scope() {
 672                 banner("Argument scope [experimental]");
 673                 fprintf(help_stream,
 674                         BETWEEN_SECTIONS
 675                         "List of arguments admitting scoping:\n"
 676                         HEADER_SPACE
 677                         "--gs              (see --ha for more details)\n"
 678                         "--gs-mo           (see --ha for more details)\n"
 679                         "--threads         (see --hp for more details)\n"
 680                         "--per-cpu         (see --hp for more details)\n"
 681                         "--perturb-upper   (see --ha for more details)\n"
 682                         "--ev              (see --hx for more details)\n"
 683                         "--black           (see --hx for more details)\n"
 684                         BETWEEN_SECTIONS
 685                         "Implicit file scope (implementation may be buggy):\n"
 686                         HEADER_SPACE
 687                         "arg1 file1 arg2   <arg2> applies only to files later than <file1>.\n"
 688                         "                    Example:\n"
 689                         "\n"
 690                         "                         --ev 10 file1 --ev 20 file2\n"
 691                         "\n"
 692                         "                    (file1 has EV 10; file2 has EV 20.)\n"
 693                         "\n"
 694                         BETWEEN_SECTIONS
 695                         "Hidden scope (implementation may be buggy):\n"
 696                         HEADER_SPACE
 697                         "[ args ]          Hide the effects of <args> options within [ ... ] scope\n"
 698                         "                    Example:\n"
 699                         "\n"
 700                         "                         file1 [ --ev 20 file2 ] file3\n"
 701                         "\n"
 702                         "                    (The EV argument is limited to file2.)\n"
 703                         "\n"
 704                         BETWEEN_SECTIONS
 705                         "Exposed scope (implementation may be buggy):\n"
 706                         HEADER_SPACE
 707                         "[ arg1 < arg2 > ] Expose the effects of <arg2> outside of [ ... ] scope\n"
 708                         BETWEEN_SECTIONS
 709                         "Fully-exposed scope (implementation may be buggy):\n"
 710                         HEADER_SPACE
 711                         "{ arg1 }          Same as [ < arg1 > ].\n"
 712                         "\n");
 713         }
 714         void process() {
 715                 banner("Process details");
 716                 fprintf(help_stream,
 717                         BETWEEN_SECTIONS
 718                         "Memory:\n"
 719                         HEADER_SPACE
 720                         "--resident <x>    Max resident megapixels per array; 0 is unlimited (0 default)\n"
 721                         BETWEEN_SECTIONS
 722                         "Profiling:\n"
 723                         HEADER_SPACE
 724                         "--profile         Output performance data\n"
 725                         BETWEEN_SECTIONS
 726                         "Thread count:\n"
 727                         "\n"
 728                         "      If the CPU count cannot be determined, the default thread count\n"
 729                         "      is 4.  Otherwise, the default is one thread per CPU.\n"
 730                         "\n"
 731                         HEADER_SPACE
 732                         "--threads <n>     Use <n> threads.\n"
 733 #ifndef USE_PTHREAD
 734                         "\n"
 735                         "                     NOTE: since this build of ALE does not link with a\n"
 736                         "                           threading library, this option is not supported.\n"
 737                         "                           To use this option, first rebuild with support\n"
 738                         "                           for threads.\n"
 739                         "\n"
 740 #endif
 741                         "--per-cpu <n>     Use <n> threads for each detected CPU.\n"
 742 #ifndef USE_PTHREAD
 743                         "\n"
 744                         "                     NOTE: since this build of ALE does not link with a\n"
 745                         "                           threading library, this option is not supported.\n"
 746                         "                           To use this option, first rebuild with support\n"
 747                         "                           for threads.\n"
 748                         "\n"
 749 #endif
 750                         "\n");
 751         }
 752         void undocumented() {
 753                 banner("Undocumented");
 754                 fprintf(help_stream,
 755                         BETWEEN_SECTIONS
 756                         "Point-spread functions:\n"
 757                         HEADER_SPACE
 758                         "--psf-match <args> Can be used to evaluate PSFs. [details are undocumented]\n"
 759                         "                      <args> are:\n"
 760                         "                          <mr> <mg> <mb> <ar> <ag> <ab>\n"
 761                         "                      where:\n"
 762                         "                          r[calibrated] = r[input] * <mr> + <ar>\n"
 763                         BETWEEN_SECTIONS
 764                         "Projective transformation calculator:\n"
 765                         HEADER_SPACE
 766                         "--ptcalc\n"
 767                         BETWEEN_SECTIONS
 768                         "Traverse subspaces for 3D candidate selection:\n"
 769                         HEADER_SPACE
 770                         "--subspace-traverse\n"
 771                         "\n"
 772                         );
 773         }
 774 };
 775
 776 #undef BETWEEN_SECTIONS
 777 #undef HEADER_SPACE