Rayshade Quick Reference

This is the Quick Reference for Rayshade 4.0.6enh. I've converted it by hand from the ASCII version after adding the syntax description for the enhancements. The User's Guide is also available and is converted from LaTeX to HTML by using Nikos Drakos' LaTeX2HTML program (<nikos@cbl.leeds.ac.uk>).

If you see any error in this description, please notify me (jvzeijl@isosa1.estec.esa.nl) and I will fix it.

Contents


Definitions

Reals and integers may be written in exponential notation, with or without a decimal point. Reals are truncated to integers when need be. Numbers may also be written as expressions surrounded by a matched pair of parentheses. Subexpressions may be parenthesized to control order of evaluation. Variables may be defined and used in parenthesized expressions. Predefined variables include time (current time) and frame (current frame number, 0 - frames-1), pi, dtor (pi/180), rtod (180/pi). Available operators are '+' (addition), '-' (subtraction and negation), '*' (multiplication), '/' (division), '%' (remainder), '^' (exponentiation). Functions include sin, cos, tan, asin, acos, atan, sqrt, and hypot.

Strings are written as non-quoted strings that may include the special characters '/' ("slash"), '-' ("dash"), '_' ("underscore), and '.' ("period"), in addition to upper and lowercase letters and non-leading digits.


Command-line options

Command-line options override options set in input file.
-A frame
First frame to render (0)
-a
Toggle alpha channel
-C cutoff
Adaptive tree cutoff (0.002)
-c
Continued rendering
-D depth
Maximum ray tree depth (5)
-E eye_sep
Eye separation
-e
Exponential RLE output
-F freq
Report frequency
-f
Flip triangle normals
-G gamma
Gamma exponent (1)
-g
Use gaussian filter
-h
Help
-j
Toggle jittered sampling
-l
Render left eye view
-m
Produce sample map
-N frames
Total frames to render (1)
-n
No shadows
-O outfile
Output file name (stdout)
-o
Toggle opaque shadows
-P cpp-args
Arguments for cpp
-p
Preview-quality (-n -S 1 -D 0)
-q
Run quietly
-R xres yres
Resolution (512 512)
-r
Right eye view
-S samples
Use Samples^2 samples (3)
-s
Toggle shadow caching
-T r g b
Contrast threshold (0.2 0.15 0.3)
-u
Toggle use of cpp
-V filename
Verbose file output
-v
Verbose output
-W lx hx ly hy
Render subwindow (0 xsize-1 0 ysize-1)
-X l r b t
Crop window (0 1 0 1)
-z filename
Write Z buffer

Syntax

Explanation of keys

[thing]
Optional item
<Thing>
Production
Thing
Number or String
(thing)
Default value(s)
thing
Keyword
thing
Keyword, with link to User's Guide
Comments start with -- and end at the end of the line.

Syntax description

File:    -- Input file consists of ...
    <Item> [<Item> ... ]

Item:
    <Viewing>
    <Light>
    <Atmosphere>
    <RenderOption>
    <ObjItem>
    <Definition>

ObjItem: -- Items used in object definition blocks
    <SurfDef>
    <ApplySurf>
    <Instance>
    <ObjDef>

Viewing:
    eyep Xpos Ypos Zpos     -- Eye position (0 -10 0)
    lookp Xpos Ypos Zpos    -- Look position (0 0 0)
    up Xup Yup Zup          -- "up" vector (0 0 1)
    fov Hfov [Vfov]         -- Field of view in degrees (horiontal=45)
    aperture Width          -- Aperture width (0)
    focaldist Distance      -- focal distance (|eyep - lookp|)
    shutter Speed           -- Shutter speed (0 = no blur)
    framelength Length      -- Length of a single frame (1)
    screen Xsize Ysize      -- Screen size (512 512)
    window Xmin Xmax Ymin Ymax -- Window (0 xsize-1 0 ysize-1)
    crop Left Right Bot Top -- Crop window (0 1 0 1)
    eyesep Separation       -- eye separation

SurfDef: -- Give a name to a set of surface attributes.
    surface Name <SurfSpec> [<SurfSpec> ...]

Surface: -- Surface specification
    <SurfSpec>                -- Use given attributes
    Surfname [<SurfSpec> ...] -- Use named surface w/ optional mods.
    cursurf  [<SurfSpec> ...] -- Use current surface w/mods - see ApplySurf

NamedSurf: -- Named surface specification
    Surfname
    cursurf

SurfSpec: -- Surface attribute specification
    ambient R G B           -- Ambient contribution
    diffuse R G B           -- Diffuse color
    specular R G B          -- Specular color
    specpow Exponent        -- Phong exponent
    body R G B              -- Body color
    extinct Coef            -- Extinction coefficient
    transp Ktr              -- Transparency, synonym for 'transparent'
    reflect Kr              -- Reflectivity, synonym for 'reflective'
    index N                 -- Index of refraction
    translu Ktl R G B Stpow -- Translucency, transmit diffuse, spec exp
                            --   synonym for 'translucency'
    noshadow                -- No shadows cast on this surface

Effect: -- Atmospheric Effects
    mist     R G B Rtrans Gtrans Btrans Zero Scale
    fog      R G B Rtrans Gtrans Btrans
    fogdeck  Altitude Offset Xscale Yscale Zscale Chaosscale Octaves
             R G B  Rthinness Gthinness Bthinness

Atmosphere: -- Global atmosphere
    atmosphere [Index] <Effect> [<Effect>...] -- Global index, effects

ApplySurf:
    applysurf <Surface> -- apply surf to all following objs w/o surface

Instance: -- Instance of an object
    <Object> [<Transforms>] [<Textures>]

Object:
    <Primitive>        -- Primitive object
    <Aggregate>        -- Named aggregate
    object [<Surface>] Objname  -- Named object

ObjDef: -- define a named object
    name Objname <Instance>

Primitive: -- Primitive object
    plane       [<Surface>] Xpos Ypos Zpos Xnorm Ynorm Znorm
    disc        [<Surface>] Radius Xpos Ypos Zpos Xnorm Ynorm Znorm
    sphere      [<Surface>] Radius Xpos Ypos Zpos
    triangle    [<Surface>] Xv1 Yv1 Zv1
                            Xv2 Yv2 Zv2  Xv3 Yv3 Zv3
                              -- flat-shaded triangle
    triangle    [<Surface>] Xv1 Yv1 Zv1 Xn1 Yn1 Zn1
                            Xv2 Yv2 Zv2 Xn2 Yn2 Zn2
                            Xv3 Yv3 Zv3 Xn3 Yn3 Zn3
                              -- Phong-shaded triangle
    triangleuv  [<Surface>] Xv1 Yv1 Zv1 Xn1 Yn1 Zn1 U1 V1
                            Xv2 Yv2 Zv2 Xn2 Yn2 Zn2 U2 V2
                            Xv3 Yv3 Zv3 Xn3 Yn3 Zn3 U3 V3
                              -- Phong-shaded triangle with uv mapping
    poly        [<Surface>] Xv1 Yv1 Zv1  -- synonym for 'polygon'
                            Xv2 Yv2 Zv2  Xv3 Yv3 Zv3 [Xv3 Yv4 Zv4 ...]
    box         [<Surface>] Xlow Ylow Zlow
                            Xhi Yhi Zhi
    cylinder    [<Surface>] Radius Xbase Ybase Zbase Xapex Yapex Zapex
    cone        [<Surface>] Rbase Xbase Ybase Zbase Rapex Xapex Yapex Zapex
    torus       [<Surface>] Rswept Rtube Xpos Ypos Zpos Xnorm Ynorm Znorm
    blob        [<Surface>] Thresh Stren Rad Xpos Ypos Zpos
                            [Stren Rad Xpos Ypos Zpos ...]
    cblob       [<Surface>] Thresh Stren Rad Xpos Ypos Zpos [<Surface>]
                            [Stren Rad Xpos Ypos Zpos [<Surface>] ...]
    heightfield [<Surface>] Filename
    fracland    [<Surface>] Seed Subdiv
    rotspline   [<Surface>] Xbase Ybase Zbase Xapex Yapex Zapex
                            coeffs c3 c2 c1 c0
    rotspline   [<Surface>] Xbase Ybase Zbase Rbase Gbase
                            Xapex Yapex Zapex Rapex Gapex
    sweptsph    <SweptSphCenter> r0 r1 r2 r3

SweptSphCenter:
    bezier    x0 y0 z0  x1 y1 z1  x2 y2 z2  x3 y3 z3
    coeffs    cx0 cx1 cx2 cx3  cy0 cy1 cy2 cy3  cz0 cz1 cz2 cz3
    xbezier   x0 x1 x2 x3
    ybezier   y0 y1 y2 y3
    zbezier   z0 z1 z2 z3
    xcoeffs   cx0 cx1 cx2 cx3
    ycoeffs   cy0 cy1 cy2 cy3
    zcoeffs   cz0 cz1 cz2 cz3

Aggregate:
    <Grid>
    <List>
    <CSG>

Grid:
    grid X Y Z <ObjItem> [<ObjItem> ...] end

List:
    list <ObjItem> [<ObjItem> ...] end

CSG:
    union      <ObjItem> <ObjItem> [<ObjItem> ...] end
    intersect  <ObjItem> <ObjItem> [<ObjItem> ...] end
    difference <ObjItem> <ObjItem> [<ObjItem> ...] end

    -- CSG will only work properly when applied to closed objects, e.g.:
    --   sphere, box, torus, blob, closed Aggregate, other CSG object

Transforms: -- Transformations
    translate  Xtrans Ytrans Ztrans
    scale      Xscale Yscale Zscale
    rotate     Xaxis Yaxis Zaxis Degrees
    transform  X1  Y1  Z1
               X2  Y2  Z2
               X3  Y3  Z3
              [Xt  Yt  Zt]

Textures:
    texture <Texture> [Transforms] [<Texture> [Transforms] ...]

Texture:
    checker   <Surface>
    blotch    Scale <Surface>
    bump      Bumpscale
    marble    [Colormapname]
    fbm       Offset Scale H Lambda Octaves Thresh [Colormapname]
    fbmbump   Offset Scale H Lambda Octaves
    wood
    gloss     Glossiness
    cloud     Scale H Lambda Octaves Cthresh Lthresh Transcale
    sky       Scale H Lambda Octaves Cthresh Lthresh
    stripe    <Surface> Width Bumpscale [<Mapping>]
    image     Imagefile [<ImageTextOption> [<ImageTextOption> ...]]
    gradient  <NamedSurf> <NamedSurf> [<GradShape>] [start stop]
              [<GradType>] [random]
    windy     Scale Wscale Cscale Bscale Octaves Tscale Hscale Offset
    mount     Colormapname Turb Slope

ImageTextOption:
    component <SurfComp>
    range     Lo Hi
    smooth
    textsurf  <Surface>
    tile      U V
    <Mapping>

SurfComp:
    ambient
    diffuse
    body
    reflect	-- synonym for 'reflective'
    transp	-- synonym for 'transparent'
    specular
    specpow
    bump
    index

Mapping:
    map uv
    map cylindrical [Xorigin Yorigin Zorigin Xup Yup Zup Xu Yu Zu]
    map planar      [Xorigin Yorigin Zorigin Xv  Yv  Zv  Xu Yu Zu]
    map spherical   [Xorigin Yorigin Zorigin Xup Yup Zup Xu Yu Zu]

GradShape:
    planar     -- default
    radial
    sperical

GradType:
    linear     -- default
    log
    revlog

Light:
    light R G B <LightType> [noshadow]
    light Intensity <LightType> [noshadow]

LightType:
    ambient
    point       Xpos Ypos Zpos
    directional Xdir Ydir Zdir
    extended    Radius Xpos Ypos Zpos
    spot        Xpos Ypos Zpos Xat Yat Zat Coef [Thetain Thetaout]
    area        Xorigin Yorigin Zorigin Xu Yu Zu Usamples Xv Yv Zv Vsamples
    projector   Imagefile [<ImageLightOption>]
                Xfrom Yfrom Zfrom
                Xto Yto Zto
                Xup Yup Zup
                Uangle
                Vangle
                Falloff_flag

ImageLightOption:
    tile        U V
    smooth

RenderOption:
    sample       Nsamp [jitter | nojitter]
                            -- Use Nsamp^2 pixel samples (3^2 jitter)
    background   R G B      -- Background color (0 0 0)
    outfile      Filename   -- Output file name (written to stdout)
    frames       Nframes    -- Number of frames to render (1)
    starttime    Time       -- Time corresponding to start of frame 0
    contrast     R G B      -- Maximum contrast w/o supersampling
    maxdepth     Depth      -- Maximum ray tree depth (5)
    cutoff       Factor     -- Minimum spawned ray contribution (.001)
    report       [verbose] [quiet] [Freq] [Statfile]
                            -- Reporting mode (false false 10 stderr)
    shadowtransp            -- Toggle object opacity affects shadows
    filter       <FilterType> [Width]
                            -- use filter with specified width
                            --  (box=1.0 gauss=1.8)
    print        Value      -- print value to stderr

FilterType:
    box          -- default
    gauss

Definition: -- Variable definition
    define Name Expr        -- Assign value for Name


Jelle van Zeijl,
-- West Consulting bv - <jelle@west.nl>
-- ESA / Estec / SAI - <jvzeijl@iso.estec.esa.nl>