Inside Multimedia 1995 December/IMM1295.ISO/share/grafik/povhelp/cmdline.hlp

Text File | 1994-07-04 | 17KB | 365 lines

    The command-line parameters may be specified in any order.  Repeated pa-
 rameters overwrite the previous values except for the +L switch which defi-
 nes include file library paths.  Up to 10 paths may be specified.  Default
 parameters may also be specified in a file called 'povray.def' or by the
 environment variable 'POVRAYOPT'.

    Switches may be specified in upper or lower case.  Switches must be pre-
 ceded by a + (plus) or - (minus).  In switches which toggle a feature, the
 plus turns it on and minus turns it off.  For example +P turns on the 'pause
 for keypress when finished' option while -P turns it off.

    Other switches are used to specify values and do not toggle a feature.
 Either plus or minus may be used in that instance.  For example: +W320 sets
 the width to 320 pixels.  You could also use -W320 and get the same results.


 Quick Reference:

 ----------------------------------------------------------------------------
 Parameter      |      Range    |   Description
 ---------------+---------------+--------------------------------------------
 +Annn          | 0.0 to 3.0    | Render picture with anti-aliasing, or
                |               | 'smoothing', on.  Lower values cause more
                |               | smoothing.
 +A             |               | Use default 0.3 anti-aliasing.
 -A             |               | Turn anti-aliasing off (default).
 +Bnnn or -Bnnn | Varies w/ sys | Output file buffer size.
 +C             |               | Continue an aborted partial image.
 -C             |               | Start rendering from first line.
 +Dxxx          | Varies w/ sys | Display image graphically while rendering
                |               | not available on all versions.
 +Enn or +ERnn  | 1 to 32,767   | End row for tracing a portion of a scene.
                | or 0.0 to 1.0 |
 +ECnn          | 1 to 32,767   | End column for tracing a portion of a
                | or 0.0 to 1.0 | scene.
 +FT            |               | Output Targa format file.
 +FD            |               | Output dump format file.
 +FR            |               | Output raw format file.
 -F             |               | Disable file output.
 +Hnnn          | 1 to 32,767   | Height of image in pixels.
 +Ifilespec     | Varies w/ sys | Input scene file name, generally ends
                |               | in .pov.
 +Jnnn.nnn      | 0.0 to 1.0    | Set amount of jitter anti-aliasing.
 +J             |               | Use anti-aliasing jitter 1 (default).
 -J             |               | Turn off anti-aliasing jitter.
 +Knnn.nnn      | Real value    | Set 'clock' float value for animation.
 +Lpathspec     | Varies w/ sys | Library path: POV-Ray will search for
                |               | files in the directory listed here.
                |               | Multiple lib paths may be specified.
 -MB            |               | Turn off bounding slabs.
 +MBnnn         | 0 to 32,767   | Use bounding slabs if more than nnn
                |               | objects in scene.
 +MSnnn         | 300 or more   | Set symbol table size (default 1000).
 +MVn.m         | 1.0 or 2.0    | Set version compatibility mode.
 +Ofilespec     | Varies w/ sys | Output image filename.
 +P             |               | Pause and wait for keypress after
                |               | tracing image.
 -P             |               | Don't pause after tracing image.
 +Qn            |   0 to 9      | Image quality: 9 highest (default) to
                |               | 0 lowest.
 +Rn or -Rn     |   1 to 9      | Use n*n rays for anti-aliasing.  Default
                |               | of 3 = 9 rays; 4 = 16 rays etc.
 +Snn or +SRnn  | 1 to 32,768   | Start row for tracing a portion of a
                | or 0.0 to 1.0 | scene.
 +SCnn          | 1 to 32,768   | Start column for tracing a portion of
                | or 0.0 to 1.0 | a scene.
 +Vnn           | Varies w/ sys | Display verbose image stats while ren-
                |               | dering.
 -V             |               | No stats during rendering.
 +Wnnn          | 1-32,768      | Width of image in pixels.
 +X             |               | Allow abort with keypress.  (IBM-PC).
 -X             |               | Disable abort with keypress.  (IBM-PC).
 ----------------------------------------------------------------------------


 Anti-Aliasing:

    +Annn         Anti-alias with tolerance level nnn.
    +A            Anti-alias with tolerance level 0.3.
    -A            Don't anti-alias (default).
    +Jn.nn        Scale factor for jittering.
    +J            Jitter AA with scale 1.0 (default).
    -J            Turn off jittering.
    +Rn or -Rn    Use n*n rays when anti-aliasing (default 3).

    Anti-aliasing is a technique used to make the image look smoother.  Often
 the color difference between two objects creates a 'jaggy' appearance.  When
 anti-aliasing is turned on, POV-Ray attempts to 'smooth' the jaggies by
 shooting more rays into the scene and averaging the results.  This technique
 can really improve the appearance of the final image.  Be forewarned though,
 anti-aliasing drastically slows the time required to render a scene since it
 has do many more calculations to 'smooth' the image.  Lower numbers mean
 more anti-aliasing and also more time.  Use anti-aliasing for your final
 version of a picture, not the rough draft.

    The +A option enables adaptive anti-aliasing.  The number after the +A
 option determines the threshold for the anti-aliasing.

    If the color of a pixel differs from its neighbor (to the left or above)
 by more than the threshold, then the pixel is subdivided and super- sampled.
 If r1,g1,b1 and r2,g2,b2 are the rgb components of two pixels then the dif-
 ference between pixels is computed by:
       diff=abs(r1-r2)+abs(g1-g2)+abs(b1-b2)

    The rgb values are in the range 0.0 to 1.0 thus the most two pixels can
 differ is 3.0.  If the anti-aliasing threshold is 0.0, then every pixel is
 super-sampled.  If the threshold is 3.0, then no anti-aliasing is done.

    The lower the contrast, the lower the threshold should be.  Higher con-
 trast pictures can get away with higher tolerance values.  Good values seem
 to be around 0.2 to 0.4.

    The super-samples are jittered to introduce noise and to eliminate moire
 interference patterns.

    NOTE: The jittering 'noise' is non-random and repeatable in nature, based
 on an object's 3-D orientation in space.  Thus, it's okay to use anti-alias-
 ing for animation sequences, as the anti-aliased pixels won't vary and
 flicker annoyingly from frame to frame.

    The +Jnn.nn switch scales down the amount of jitter from its default va-
 lue 1.0.  For example +J0.5 uses half the normal jitter.  Values over 1.0
 jitter outside the pixel bounds and are not recommended.  Use -J to turn off
 jittering.

    The +R switch controls the number of rows and columns of rays per pixel
 with anti-aliasing.  The default value 3 gives 3x3=9 rays per pixel.  The
 jittering and multiple rays are only used when +A is on.


 Buffering:

    +Bnnn    Use an output file buffer of nnn kilobytes.
    -Bnnn    Same as +Bnnn.

    The +B option allows you to assign large buffers to the output file.
 This reduces the amount of time spent writing to the disk.  If this parame-
 ter is not specified, then as each scanline is finished, the line is written
 to the file and the file is flushed.  On most systems, this operation insu-
 res that the file is written to the disk so that in the event of a system
 crash or other catastrophic event, at least part of the picture has been
 stored properly and retrievable on disk.  (see also the +C option below.)
 A value of +B30 is a good value to use to speed up small renderings.  A va-
 lue of +B0 defaults to a small system-dependent buffer size.

    NOTE: Neither +B0 nor -B turns this feature off.  Once a buffer is set,
 subsequent +B commands can change its size but cannot turn it off.


 Continuing Interrupted Trace:

    +C    Continue partially complete rendering.
    -C    Render from beginning (default).

    If you abort a render while it's in progress or if you used the +E or +ER
 options to end the render prematurely, you can use the +C option to continue
 the render when you get back to it.  This option reads in the previously ge-
 nerated output file, displays the image to date on the screen, then proceeds
 with the ray tracing.  This option cannot be used if file output is disabled
 with -F.  It does not work with +S, +SR, +SC or +EC switches.


 Display Preview Image:

    +D    Use preview display.
    -D    Turn preview display off (default).

    If the +D option is used and your computer supports a graphic display,
 then the image will be displayed while the program performs the ray tracing.
 On most systems, the picture displayed is not as good as the one created by
 the post-processor because it does not try to make optimum choices for the
 color registers.  The +D parameters are system-dependent and are listed in
 the executable documentation.


 Render Partial Image:

    +Snnn or +SRnnn    Start tracing at row number nnn.
    +SCnnn             Start tracing at column number nnn.
    +Ennn or +ERnnn    End tracing at row number nnn.
    +ECnnn             End tracing at column number nnn.

    When doing test rendering it is often convenient to define a rectangular
 section of the whole screen so you can quickly check out one area of the
 image.  The +S and +E switches let you define starting and ending rows and
 columns for partial renderings.

    The +S and +E options also allow you to begin and end the rendering of an
 image at a specific scan line so you can render groups of scanlines on dif-
 ferent systems and concatenate them later.

    WARNING: Image files created on with different executables on the same or
 different computers may not look exactly the same due to different random
 number generators used in some textures.  If you are merging output files
 from different systems, make sure that the random number generators are the
 same.  If not, the textures from one will not blend in with the textures
 from the other.

    NOTE: If the number following +SR, +SC, +ER or +EC is a greater 1 then it
 is interpreted as a number of pixels.  If it is a decimal value between 0.0
 and 1.0 then it is interpreted as a percent of the total width or height of
 the image.  For example: +SR0.75 +SC0.75 starts on a row 75% down from the
 top at a column 75% from the left and thus renders only the lower- right 25%
 of the image.


 File Output Format:

    +FT    Uncompressed Targa-24 format (IBM-PC Default).
    +FD    Dump format (QRT-style).
    +FR    Raw format - one file each for Red, Green and Blue.
    +F      Use default file type for your system.
    -F      Turn off file output.

    Normally, you don't need to specify any form of +F option.  The default
 setting will create the correct format image file for your computer.  The
 documentation included with the executable specify which format is used.

    You can disable image file output by using the command line option -F.
 This is only useful if your computer has display options and should be used
 in conjunction with the +P option.  If you disable file output using -F,
 there will be no record kept of the image file generated.  This option is
 not normally used.

    Unless file output is disabled (-F) POV-Ray will create an image file of
 the picture.  This output file describes each pixel with 24 bits of color
 information.  Currently, three output file formats are directly supported.
 They are +FT - Uncompressed Targa-24 format (IBM-PC Default), +FD - Dump
 format (QRT-style) and +FR - Raw format - one file each for Red, Green and
 Blue.


 Height and Width of Image:

    +Hnnn or -Hnnn    Set height of image in pixels.
    +Wnnn or -Wnnn    Set width of image in pixels.

    These switches set the height and width of the image in pixels.  This
 specifies the image size for file output.  The preview display with the +D
 option will generally attempt to pick a video mode to accommodate this size
 but the +D settings do not in any way affect the resulting file output.


 Input and Output File Names:

    +Ifilename    Set the input filename.
    +Ofilename    Set output filename.

    The default input filename is 'object.pov'.  The default output filename
 is 'data' and the suffix for your default file type.  The +O switch has no
 effect unless file output is turned on with +F.  IBM-PC default file type is
 Targa, so the file is 'data.tga'.

    Raw mode writes three files, 'data.red', 'data.grn' and 'data.blu'.   On
 IBM-PC's, the default extensions for raw mode are '.r8', '.g8', and '.b8' to
 conform to Piclab's 'raw' format.  Piclab is a widely used freeware image
 processing program.  Normally, Targa files are used with Piclab, not raw
 files.


 Animation Clock Variable:

    +Knnn or -Knnn    Set the 'clock' float value.

    The +K switch may be used to pass a single float value to the program for
 basic animation.  The value is stored in the float identifier 'clock'.  If
 an object had a 'rotate <0,clock,0>' attached then you could rotate the ob-
 ject by different amounts over different frames by setting +K10, +K20, etc.
 on successive renderings.


 Library Search Path:

    +Lpathspec    Specify one of 10 library search paths.

    The +L option may be used to specify a 'library' pathname to look in for
 include, parameter and image files.  Multiple uses of the +L switch do not
 override previous settings.  Up to ten +L options may be used to specify a
 search path.  The home (current) directory will be searched first followed
 by the indicated library directories in order.


 Bounding Slabs Control:

    -MB       Turn off bounding slabs.
    +MBnnn    Use bounding slabs if more than nnn objects in scene.

    New to POV-Ray version 2.0 is a spatial sub-division system called bound-
 ing slabs.  It compartmentalizes all of the objects in a scene into rectan-
 gular slabs and computes which slabs a particular ray hits before testing
 the objects within the slab.  This can greatly improve rendering speed, how-
 ever for scenes with only a few objects the overhead of using slabs is not
 worth the effort.  The +MB switch sets the minimum number of objects before
 slabs are used.  The default is +MB25.  The -MB switch turns off slabs com-
 pletely.


 Symbol Table Size:

    +MSnnn or -MSnnn    Sets symbol table size (default 1000).

    POV-Ray allocates a fixed number of spaces in its symbol table for decla-
 red identifiers.  The default of 1000 may be increased if you get a 'Too
 many symbols' error message.


 Version Compatibility Mode:

    +MVn.n or -MVn.n    Set version compatibility mode.

    While many language changes have been made for POV-Ray 2.0, most version
 1.0 syntax still works.  One new feature in 2.0 that is incompatible with
 any 1.0 scene files is the parsing of float expressions.  Setting +MV1.0
 turns off expression parsing as well as many warning messages so that nearly
 all 1.0 files will still work.  The '#version' language directive also can
 be used to change modes within scene files.  The +MV switch affects only the
 initial setting.


 Pause When Finished:

    +P    Pause when image is complete so preview image can be seen.
    -P    Do not pause (default).

    Normally when preview display is on you want to look at the image awhile
 before continuing.  The +P switch pauses and waits for you to press a key
 before going on.


 Quality Settings:

    +Qn or -Qn    Set rendering quality.

    The +Q option allows you to specify the image rendering quality, for
 quickly rendering images for testing.  You may also use -Q with no differ-
 ence.  The parameter can range from 0 to 9.  The values correspond to the
 following quality levels:
       0,1 => Just show quick colors.  Ambient lighting only.
              Quick colors are used only at 5 or below.
       2,3 => Show Diffuse and Ambient light
       4,5 => Render shadows, use extended lights at 5 but not 4.
       6,7 => Create surface textures.
       8,9 => Compute reflected, refracted, and transmitted rays.

    The default is +Q9 (maximum quality) if not specified.


 Verbose Statistics:

    +V    Verbose statistics on.
    -V    Verbose statistics off.

    When the +D option is not used, it is often desirable to monitor progress
 of the rendering.  The +V switch turns on verbose reporting while -V turns
 it off.  The format of the output is system dependent.


 Allow Aborted Rendering:

    +X    Allow abort with keypress.
    -X    Disable abort with keypress.

    On the IBM-PC versions only, when you specify the +X switch then any key-
 press will abort rendering.  The -X switch disables this feature.