### Section 7
Scene Description Language

The Scene Description Language allows you to describe the world in a readable and convenient way. Files are created in plain ASCII text using an editor of your choice. The input file name is specified using the Input_File_Name=file option or +I file switch. By default the files have the extension .pov. POV-Ray reads the file, processes it by creating an internal model of the scene and then renders the scene.

The overall syntax of a scene is a file that contains any number of the following items in any order.

       LANGUAGE_DIRECTIVES
       camera { CAMERA_ITEMS }
       OBJECT_STATEMENTS
       ATMOSPHERE_STATEMENTS
       global_settings { GLOBAL_ITEMS }

See section "Language Directives", section "Objects", section "Camera", section "Atmospheric Effects" and section "Global Settings" for details.

### Section 7.1
Language Basics

The POV-Ray language consists of identifiers, reserved keywords, floating point expressions, strings, special symbols and comments. The text of a POV-Ray scene file is free format. You may put statements on separate lines or on the same line as you desire. You may add blank lines, spaces or indentations as long as you do not split any keywords or identifiers.

### Section 7.1.1
Identifiers and Keywords

POV-Ray allows you to define identifiers for later use in the scene file. An identifier may be 1 to 40 characters long. It may consist of upper or lower case letters, the digits 0 through 9 or an underscore character ("_"). The first character must be an alphabetic character. The declaration of identifiers is covered later.

POV-Ray has a number of reserved keywords which are listed below.

    aa_level                 fog_offset           reciprocal
    aa_threshold             fog_type             recursion_limit
    abs                      frequency            red
    acos                     gif                  reflection
    acosh                    global_settings      refraction
    adaptive                 glowing              render
    adc_bailout              gradient             repeat
    agate                    granite              rgb
    agate_turb               gray_threshold       rgbf
    all                      green                rgbft
    alpha                    halo                 rgbt
    ambient                  height_field         right
    ambient_light            hexagon              ripples
    angle                    hf_gray_16           rotate
    aperture                 hierarchy            roughness
    arc_angle                hollow               samples
    area_light               hypercomplex         scale
    asc                      if                   scallop_wave
    asin                     ifdef                scattering
    asinh                    iff                  seed
    assumed_gamma            image_map            shadowless
    atan                     incidence            sin
    atan2                    include              sine_wave
    atanh                    int                  sinh
    atmosphere               interpolate          sky
    atmospheric_attenuation  intersection         sky_sphere
    attenuating              inverse              slice
    average                  ior                  slope_map
    background               irid                 smooth
    bicubic_patch            irid_wavelength      smooth_triangle
    black_hole               jitter               sor
    blob                     julia_fractal        specular
    blue                     lambda               sphere
    blur_samples             lathe                spherical_mapping
    bounded_by               leopard              spiral
    box                      light_source         spiral1
    box_mapping              linear               spiral2
    bozo                     linear_spline        spotlight
    break                    linear_sweep         spotted
    brick                    location             sqr
    brick_size               log                  sqrt
    brightness               looks_like           statistics
    brilliance               look_at              str
    bumps                    low_error_factor     strcmp
    bumpy1                   mandel               strength
    bumpy2                   map_type             strlen
    bumpy3                   marble               strlwr
    bump_map                 material_map         strupr
    bump_size                matrix               sturm
    camera                   max                  substr
    case                     max_intersections    superellipsoid
    caustics                 max_iteration        switch
    ceil                     max_trace_level      sys
    checker                  max_value            t
    chr                      merge                tan
    clipped_by               mesh                 tanh
    clock                    metallic             test_camera_1
    color                    min                  test_camera_2
    color_map                minimum_reuse        test_camera_3
    colour                   mod                  test_camera_4
    colour_map               mortar               text
    component                nearest_count        texture
    composite                no                   texture_map
    concat                   normal               tga
    cone                     normal_map           thickness
    confidence               no_shadow            threshold
    conic_sweep              number_of_waves      tightness
    constant                 object               tile2
    control0                 octaves              tiles
    control1                 off                  torus
    cos                      offset               track
    cosh                     omega                transform
    count                    omnimax              translate
    crackle                  on                   transmit
    crand                    once                 triangle
    cube                     onion                triangle_wave
    cubic                    open                 true
    cubic_spline             orthographic         ttf
    cylinder                 panoramic            turbulence
    cylindrical_mapping      pattern1             turb_depth
    debug                    pattern2             type
    declare                  pattern3             u
    default                  perspective          ultra_wide_angle
    degrees                  pgm                  union
    dents                    phase                up
    difference               phong                use_color
    diffuse                  phong_size           use_colour
    direction                pi                   use_index
    disc                     pigment              u_steps
    distance                 pigment_map          v
    distance_maximum         planar_mapping       val
    div                      plane                variance
    dust                     png                  vaxis_rotate
    dust_type                point_at             vcross
    eccentricity             poly                 vdot
    else                     polygon              version
    emitting                 pot                  vlength
    end                      pow                  vnormalize
    error                    ppm                  volume_object
    error_bound              precision            volume_rendered
    exp                      prism                vol_with_light
    exponent                 pwr                  vrotate
    fade_distance            quadratic_spline     v_steps
    fade_power               quadric              warning
    falloff                  quartic              warp
    falloff_angle            quaternion           water_level
    false                    quick_color          waves
    file_exists              quick_colour         while
    filter                   quilted              width
    finish                   radial               wood
    fisheye                  radians              wrinkles
    flatness                 radiosity            x
    flip                     radius               y
    floor                    rainbow              yes
    focal_point              ramp_wave            z
    fog                      rand
    fog_alt                  range

    All reserved words are fully lower case. Therefore it is recommended
    that your identifiers contain at least one upper case character so it
    is sure to avoid conflict with reserved words.

    The following keywords are in the above list of reserved keywords but
    are not currently used by POV-Ray however they remain reserved.

      bumpy1               test_camera_1
      bumpy2               test_camera_2
      bumpy3               test_camera_3
      incidence            test_camera_4
      pattern1             track
      pattern2             volume_object
      pattern3             volume_rendered
      spiral               vol_with_light

### Section 7.1.2
Comments

Comments are text in the scene file included to make the scene file easier to read or understand. They are ignored by the ray-tracer and are there for your information. There are two types of comments in POV-Ray.

Two slashes are used for single line comments. Anything on a line after a double slash (//) is ignored by the ray-tracer. For example:

      // This line is ignored

You can have scene file information on the line in front of the comment as in:

      object { FooBar }  // this is an object

The other type of comment is used for multiple lines. It starts with "/*" and ends with "*/". Everything in-between is ignored. For example:

      /* These lines
         are ignored
         by the
         ray-tracer */

This can be useful if you want to temporarily remove elements from a scene file. /* ... */ comments can comment out lines containing other // comments and thus can be used to temporarily or permanently comment out parts of a scene. /* ... */ comments can be nested, the following is legal:

      /* This is a comment
      // This too
      /* This also */
      */

Use comments liberally and generously. Well used, they really improve the readability of scene files.

### Section 7.1.3
Float Expressions

Many parts of the POV-Ray language require you to specify one or more floating point numbers. A floating point number is a number with a decimal point. Floats may be specified using literals, identifiers or functions which return float values. You may also create very complex float expressions from combinations of any of these using various familiar operators.

Where POV-Ray needs an integer value it allows you to specify a float value and it truncates it to an integer. When POV-Ray needs a logical or boolean value it interprets any non-zero float as true and zero as false. Because float comparisons are subject to rounding errors POV-Ray accepts values extremely close to zero as being false when doing boolean functions. Typically values whose absolute values are less than a preset value epsilon are considered false for logical expressions. The value of epsilon is system dependent but is generally about 1.0e-10. Two floats a and b are considered to be equal if abs(a-b) < epsilon.

### Section 7.1.3.1
Float Literals

Float literals are represented by an optional sign ("+" or "-") digits, an optional decimal point and more digits. If the number is an integer you may omit the decimal point and trailing zero. If it is all fractional you may omit the leading zero. POV-Ray supports scientific notation for very large or very small numbers. The following are all valid float literals:

      -2.0    -4    34    3.4e6    2e-5    .3    0.6

### Section 7.1.3.2
Float Identifiers

Float identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.

      #declare IDENTIFIER = EXPRESSION

Where IDENTIFIER is the name of the identifier up to 40 characters long and EXPRESSION is any valid expression which evaluates to a float value. Here are some examples.

      #declare Count = 0
      #declare Rows = 5.3
      #declare Cols = 6.15
      #declare Number = Rows*Cols
      #declare Count = Count+1

As the last example shows, you can re-declare a float identifier and may use previously declared values in that re-declaration. There are several built-in identifiers which POV-Ray declares for you. See "Built-in Identifiers" for details.

### Section 7.1.3.3
Float Operators

Arithmetic float expressions can be created from float literals, identifiers or functions using the following operators in this order of precedence...

      ()             expressions in parentheses first
      +A   -A   !A   unary minus, unary plus and logical "not"
      A*B  A/B       multiplication and division
      A+B  A-B       addition and subtraction

Relational, logical and conditional expressions may also be created. However there is a restriction that these types of expressions must be enclosed in parentheses first. This restriction, which is not imposed by most computer languages, is necessary because POV-Ray allows mixing of float and vector expressions. Without the parentheses there is an ambiguity problem. Parentheses are not required for the unary logical not operator "!" as shown above. The operators and their precedence are shown here.

Relational expressions: The operands are arithmetic expressions and the result is always boolean with 1 for true and 0 for false. All relational operators have the same precedence.

(A < B) | A is less than B
(A <= B) | A is less than or equal to B
(A = B) | A is equal to B (actually abs(A-B)<EPSILON)
(A != B) | A is not equal to B (actually abs(A-B)>=EPSILON)
(A >= B) | A is greater than or equal to B
(A > B) | A is greater than B

Logical expressions: The operands are converted to boolean values of 0 for false and 1 for true. The result is always boolean. All logical operators have the same precedence. Note that these are not bit-wise operations, they are logical.

(A & B) | true only if both A and B are true, false otherwise
(A | B) | true if either A or B or both are true

Conditional expressions: The operand C is boolean while operands A and B are any expressions. The result is of the same type as A and B.

(C ? A : B) | if C then A else B

Assuming the various identifiers have been declared, the following are examples of valid expressions...

      1+2+3       2*5         1/3         Row*3       Col*5
      (Offset-5)/2            This/That+Other*Thing
      ((This<That) & (Other>=Thing)?Foo:Bar)

Expressions are evaluated left to right with innermost parentheses evaluated first, then unary +, - or !, then multiply or divide, then add or subtract, then relational, then logical, then conditional.

Next Section
Table Of Contents