.POV File Format

Introduction

A .pov file is a scene for POV-Ray, the Persistence of Vision Raytracer: a text file in the scene description language (SDL) that says what the picture shows. It names a camera, light sources and objects (spheres, boxes, meshes, isosurfaces, unions and cut-outs of them), and describes the surface of each object with textures made of pigments, normals and finishes. POV-Ray reads the text, traces rays through every pixel and writes an image. The same language is a small programming language: it has declarations, expressions, vectors and arrays, functions, loops, conditions and macros, so a scene can build thousands of objects from a few lines.

A scene is plain text with C-like comments. Words are case sensitive and written in lower case, blocks are written in braces, and the numbers of a vector are written in angle brackets (<0, 1, 0>). Lines that start with # are directives for the preprocessor (#declare, #include, #macro, #while and others). Larger scenes keep shared parts in include files (.inc), and the render settings (size, quality, anti-aliasing, animation) are given in an INI file or on the command line. These pages describe the language as the tokenizer and parser of POV-Ray 3.8 read it: file types and structure, lexical structure, reserved words, directives, expressions, functions, every object, every modifier, textures, media, cameras, lights, global settings, the include files, the INI options and the differences between the versions 3.0 and 3.8.

#version 3.8;
#include "colors.inc"

global_settings { assumed_gamma 1.0 }

camera {
  location <0, 2, -6>
  look_at  <0, 1, 0>
}

light_source { <5, 8, -5> color White }

plane { y, 0 pigment { checker color Gray80 color Gray20 } }

sphere {
  <0, 1, 0>, 1
  texture {
    pigment { color Red }
    finish { phong 0.8 reflection 0.1 }
  }
}

The kinds of file

The viewer registers .pov and tells the .inc files of POV-Ray from the other .inc files; the language names pov, povray and pov-ray colour a Markdown code block.

How the viewer reads each file

A .pov file, and a .inc file that reads as POV-Ray, is shown as coloured text. Nothing is rendered: this site has no renderer for the language. The scanner follows the tokenizer of POV-Ray 3.8 (scanner.cpp, rawtokenizer.cpp and the table of reserved words): comments that nest, words that are case sensitive, the 523 reserved words in four colours (functions, constants, objects and the other keywords), numbers, strings with their escapes, the directive after a #, and the names that the file declares. Beside the text the viewer lists:

• Outline – every #declare and #local at the top level (with what it is set to), every #macro (with its parameters), the objects, the camera, the light sources and the scene settings at the top level, and every #include, each with its line
• Includes – the files that the scene includes, in order, with their lines
• Problems – what the scanner can find without running the scene: a comment or a string that is not closed, brackets that do not match, a directive that does not exist, #end, #else, #case and #range in the wrong place, a block directive that is never closed, and a character that POV-Ray rejects outside a string or a comment. Every problem is listed, in pages, with its line

The scanner does not run the scene. It cannot know which branch of a #if is taken, so it reads every branch as code; when the branches of one conditional open different brackets it does not judge the brackets of the file at all. A name is coloured as a variable when the file declares it, not when an include file does.

The pages

• File types and structure – the file types, how a scene is laid out and what a render reads
• Lexical structure – white space, comments, identifiers, numbers, strings and escapes
• Reserved words – all 523 words by group
• Preprocessor directives – #declare, #local, #macro, #while, #if, #include, the file and message directives
• Expressions, vectors and identifiers – operators, vectors, colours, strings, arrays, splines and the kinds of identifier
• Functions and constants – the built-in functions and constants, and the function type
• Finite objects – box, sphere, cylinder, cone, torus, lathe, prism, sor, text, blob and the other solids and patches
• Infinite and implicit objects – plane, poly, quartic, quadric, isosurface, parametric and height_field
• Meshes – mesh and mesh2
• Constructive solid geometry – union, intersection, difference and merge
• Object modifiers – transformations, bounding, clipping, flags and photons settings of an object
• Textures and pigments – texture, pigment, colours and image maps
• Normals and finishes – bumps, ambient, diffuse, phong, specular, reflection, iridescence
• Patterns and maps – every pattern, the map types and the pattern modifiers
• Media, interior and atmosphere – media, interior, fog, rainbow and sky_sphere
• Cameras – camera types and their keywords
• Light sources – point, spot, cylinder and area lights, and light groups
• Global settings, radiosity and photons – global_settings and everything inside it
• INI options and switches – every option of an INI file and of the command line
• Include files – the standard include files and the conventions of .inc files
• Versions 3.0 to 3.8 – what changed from version to version and what #version does
• Tooling – the povray program, its front ends and editors

Not described

Known, not yet covered

• Viewer: the scene is not rendered. There is no POV-Ray WebAssembly build and no renderer of our own here, so a scene is shown as text with its outline, includes and problems.
• Viewer: the scanner does not run the language: it does not evaluate #if and #switch, does not follow includes, and does not check that a name is declared before it is used or that a block holds only what its object allows. The real parser finds those errors; the viewer lists only the problems of the text itself.
• Viewer: a name is coloured as a variable when this file declares it with #declare, #local, #macro, #for or #fopen; names declared in an include file stay plain.
• Reference: the pages follow the documentation of POV-Ray 3.8 that ships with its source and the source of its parser; behaviour of the versions before 3.7 is described only as far as that documentation and the changelog say.

Links