CephaloPOV v0.0.4α
User's Manual

Snapshot Mode

Snapshot mode is arguably the easier of the two animation modes to get started with, especially if the animation is simple or you want to construct your own animation loop to suit your needs. Just set cpov.settings.snapshotMode to true, which disables the built-in loop.

All you need to do after that is create your objects and call their snapshot methods. If you move them afterwards, you can call snapshot again to "plot" them in their new positions. And once you've created a snapshot of every object you want in the frame, call cpov.outputFrame to generate the .pov/.ini files and clear the snapshot buffer.

Two things are important to remember in snapshot mode. First, your light sources and cameras are objects themselves, so you have to remember to add their snapshots to the buffer in each frame. Second, objects don't magically cease to exist if you only use them once. This may not matter much in short, simple animations, but if you are creating a lot of single-use objects, you'll want to call their destroy methods to avoid filling up memory.

The script that generates the illustrations for this documentation uses snapshot mode. Here's a somewhat simplified version of what it does. (See /docs/illus.js if you want to dig into the full, somewhat hairy details.) First, it just does the usual setup and housekeeping, the only germane part of which is the first line that activates snapshot mode:

Then it creates the generic texture string that all of the object examples reuse, and it calls an undocumented internal function to produce the stage objects, which come as an array with two members, the stage and lights, and the camera. We go ahead and push those right into the snapshot buffer.

Because this isn't actually an animation, the script sets cpov.settings.outputBase at the beginning of each "frame" to make it easier to find the files. (I'm mentioning this to point out that snapshot mode is also a convenient way to crank out a bunch of static images.)

Now we can get down to business and create our example box:

And that's it as far as objects go. We just need to output the frame and clean up after ourselves:

Naturally, if you're only doing a single frame or a short animation with relatively few objects, you don't have to bother with calling destroy, but it's a good habit to get into before you start working on more ambitious projects.

Automatic Mode

Automatic mode is not actually any harder to use than snapshot mode. In fact, it's a lot easier because it automates a lot of the stuff you'd otherwise have to do manually, but it does require you to understand the CephaloPOV animation loop, at least if you want to avoid tying yourself into knots. Let's just get that out of the way first:

1. The global cpov.settings.frameBegin callback is called.
2. Each object's individual frameBegin callback is called.
3. All active objects are written to file by cpov.outputFrame.
4. Each object's individual frameEnd callback is called.
5. The global cpov.settings.frameEnd callback is called.
6. The cpov.clockTime is incremented by cpov.tickVal and cpov.currentFrame is incremented.

This loop starts when your program calls cpov.runAnimation and continues until either your program calls cpov.endAnimation, cpov.clockTime exceeds cpov.endTime, or cpov.currentFrame exceeds cpov.endFrame. Besides setting up the initial scene, all you have to do is write the necessary beginFrame and endFrame callbacks.

Callbacks

As far as the callbacks are concerned, how you want to structure things is up to you. If you want, you can stuff all of your logic into cpov.beginFrame and/or cpov.endFrame. You can also leave them set to null and pack everything into the beginFrame and endFrame methods of individual objects. You can also use both. CephaloPOV is not opinionated about your code.

All of the callbacks are the same. Each one is called with a single argument, the global cpov object, which it can then interrogate to determine the current clock value and frame number, as well as use cpov.serialMap or cpov.idMap to find other objects. You can feel free to attach additional data and function members to cpov as well.

Using the Clock and the Frame Count

The animation clock, cpov.clockTime, is a continuous floating-point value that is incremented by cpov.tickVal at the end of each frame and measures time inside the animation. The current frame number, cpov.currentFrame, is a discrete integer value that increases by one at the end of each frame, and which effectively measures the number of times that the simulated world of the animation has been sampled.

You can just use one or the other if your needs are simple enough, but the combination of the two is powerful enough to make it worth understanding their relationship. [TODO]

The cpov Object

From the POV of user programs (see what I did there?), CephaloPOV appears as the global object cpov, so named because it would be a pain to have to type CephaloPOV all the time. Trust me, I know. The innards of cpov are actually pretty short and simple because its main job is to keep track of various settings and just run the user program. Most of the gnarly code lives elsewhere. It does have a few oft-used public methods which will be described after the parameter objects. For a complete list, see the developer documentation.

POV-Ray has two sets of global parameters which remain separate here. The first, represented in CephaloPOV by the cpov.imageOptions object, corresponds to POV-Ray's command line switches and the contents of .ini files. The second is the global_settings block in .pov scene files, which is represented by cpov.globalSettings.

In addition to these, there is a third object, cpov.settings, that contains parameters specific to CephaloPOV to avoid confusion with the POV-Ray specific settings in the other two objects.

cpov.settings

The cpov.settings objects represents the global parameters controlling the operation of CephaloPOV. Some can be set indirectly by command line switches or the config files. All of them are directly accessible to user programs.

Attributes

Methods

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers. User programs will rarely have to call the Settings constructor directly as cpov.settings is already initialized.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

cpov.imageOptions

The cpov.imageOptions object represents the global parameters that are set either by POV-Ray command line switches or by .ini files. CephaloPOV itself never uses the command line switches, but they are output in a comment at the beginning of the generated .ini files for the curious. It should be noted that not all of the values that can be set in a .ini file have corresponding command line switches.

By default, CephaloPOV initializes cpov.imageOptions with an ImageOptions object at the beginning of a job. You can create additional ImageOptions objects, but only the one assigned to cpov.imageOptions when cpov.outputFrame() is called is actually used.

All of the parameters are optional except for height and width.

Attributes

Methods

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers. User programs will rarely have to call the ImageOptions constructor directly as cpov.imageOptions is already initialized.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

cpov.globalSettings

The cpov.globalSettings class defines the behavior of light in the image along with a few odds and ends like the character set used for input files. At startup, cpov.globalSettings is initialized with a pristine instance of the GlobalSettings class. None of its parameters are mandatory except for assumedGamma, which is initialized to a default value of 1.0.

Attributes

Methods

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers. User programs will rarely have to call the GlobalSettings constructor directly as cpov.globalSettings is already initialized.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

cpov Methods

This section only lists public methods commonly used in user programs. For the complete list, see the developer documentation.

Converts the value of deg from degrees to radians and returns the result.

When called by the user program, this method terminates the animation loop. If a frame is in progress when it is called, it will not be output, so it is normally called after file output.

Outputs an error message using pretty colors if supported by the terminal. The level argument may be one of "fatal", "warn", "info", or "debug". If level is "fatal", the program terminates immediately unless cpov.settings.debug is greater than 1. (This is useful for debugging when working on CephaloPOV itself.) All other error levels simply emit an error message. This will appear on the terminal for "warn", "info", and "debug" at cpov.verbosity levels of 1, 2, and 3, respectively. In all cases, the error will also be written to cpov.settings.debugLog if initialized.

The error message is prefixed with the location where the error occurred, usually a class and method name, and the object serial and id, if any, are appended to the end of the line.

The cpov.outputFrame method exists for user programs to call whenever they have finished setting up a scene. It takes no arguments, its behavior being determined mostly by cpov.imageOptions and cpov.globalSettings. That behavior is already described in great detail in The Animation Cycles and will not be repeated here.

There is no return value. If any termination conditions are met, CephaloPOV will terminate with an exit code of 0.

CephaloPOV includes a number of optional libraries that are not automatically loaded at runtime. Each is identified by a mnemonic alias passed to cpov.requireOptLib, which in turn loads the library and returns it to the caller. Many of these are ports of POV-Ray include files to JavaScript identified by their original filename, e.g., colors.inc.

This is the main animation loop which repeats, calling cpov.outputFrame() repeatedly until one of its termination conditions are met or the user program calls cpov.endAnimation.

Vectors, Colors, and Matrices

Most of the geometry in POV-Ray is defined in terms of vectors, i.e., arrays of floats whose interpretation depends on context. For the sake of better type checking, CephaloPOV implements vectors as distinct classes even though some of them, like VectorUV and VectorXY, are identical save for their attribute names.

Because initializing vector objects involves more typing than POV-Ray's admirably concise generic notation, all of CephaloPOV's vector types and other object methods that accept vectors will take JavaScript arrays as initializers in addition to the generic JavaScript objects that all CephaloPOV class constructors accept.

Like most CephaloPOV objects, all of the vector classes have a toSDL() method which returns the vector in the form of an SDL string.

VectorUV

The VectorUV class is used to define 2D coordinates on the UV plane for texture mapping. Aside from having coordinates named u and v, it is otherwise identical to VectorXY.

Attributes

Methods

Depending on the value of mode, returns the internal coordinates as a two-element array or, in one case, a null indicating an error condition. The legal values of mode and their results are:

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers, an array of two floats, or another VectorUV object. The following are all equivalent:

Returns the SDL representation of the vector as a string, indented by the optional number of tab stops. If the mandatory attributes are not specified, a fatal error message is emitted and CephaloPOV halts.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

VectorXY

The VectorXY class is used to define 2D coordinates. It is mostly used to define splines and the outlines of objects which are essentially sweeps, like the Prism. (For prisms, the points defined are actually on the XZ plane and the shape is swept along the Y axis, but coming up with a separate VectorXZ seems excessively pedantic.

Attributes

Methods

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers, an array of two floats, or another VectorXY object. The following are all equivalent:

Depending on the value of mode, returns the internal coordinates as a two-element array or, in one case, a null indicating an error condition. The legal values of mode and their results are:

Returns the SDL representation of the vector as a string, indented by the optional number of tab stops. If the mandatory attributes are not specified, a fatal error message is emitted and CephaloPOV halts.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

VectorXYZ

Probably the most commonly used vector type for most users, the VectorXYZ class defines points in three-dimensional space.

Attributes

Methods

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers, an array of three floats, or another VectorXYZ object. The following are all equivalent:

Depending on the value of mode, returns the internal coordinates as a three-element array or, in one case, a null indicating an error condition. The legal values of mode and their results are:

Returns the SDL representation of the vector as a string, indented by the optional number of tab stops. If the mandatory attributes are not specified, a fatal error message is emitted and CephaloPOV halts.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

VectorXYZW

The VectorXYZW class defines points in four-dimensional space, and as such, it is not often used. One use case is the four-dimensional JuliaFractal. In the Polynomial type, it is used as a convenient (and somewhat hackish) way of grouping sets of four floats that are not actually coordinates.

Attributes

Methods

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers, an array of four floats, or another VectorXYZW object. The following are all equivalent:

Depending on the value of mode, returns the internal coordinates as a four-element array or, in one case, a null indicating an error condition. The legal values of mode and their results are:

Returns the SDL representation of the vector as a string, indented by the optional number of tab stops. If the mandatory attributes are not specified, a fatal error message is emitted and CephaloPOV halts.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

Color

The Color class is used to represent RGB colors. In addition to the usual r, g, and b attributes, it has two optional attributes, f (filter) and t (transmit). There is a final optional boolean attribute, sRGB which, if true, maps the colors to the sRGB color space.

Attributes

Methods

The constructor may be called without arguments, returning an object with its attributes initialized to null. The options argument may also be a plain JavaScript object containing named initializers, an array of three to six values, or another Color object. The following are all equivalent:

Note that the f, t, and srgb attributes are optional, so none, any, or all of them can be used, but they must be specified in order when passing a bare array.

Returns the SDL representation of the vector as a string, indented by the optional number of tab stops. If the mandatory attributes are not specified, a fatal error message is emitted and CephaloPOV halts.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

Matrix

The Matrix type is the workhorse of transformations and one of the areas where CephaloPOV differs most from the way POV-Ray handles transformations, though this is more a matter of syntax than anything else.

Attributes

Methods

In its basic form, which few users will often use, the constructor takes twelve floats for each of the values in the matrix, just as it is done in SDL. Like SDL, there are several short convenience forms for the basic transformations:

In the first set of the examples above, the name of the transformation is the first argument, followed by three float arguments, one for each of the axes. In the second set, the single float is applied to all three axes. As with POV-Ray, the values for rotations are given in degrees.

The Matrix constructor has a few additional short forms. One lets you specify skews without having to construct the whole matrix by hand. Just pass "skew" as the first argument, and the second argument is an object containing the axis pairs to perform the skew by, like so:

The complete set of axis pairs is yx, zx, xy, zy, xz, and yz. You can omit the pairs you don't need.

In another, you can just pass "none" as the sole argument and get a Matrix that does nothing. This is useful if your "base" transformation (see the Primitive type for more details) doesn't require any actual transformations.

Depending on the value of mode, returns the internal matrix representation as a 12-element array or, in one case, a null indicating an error condition. The legal values of mode and their results are:

Copies the values from that to this Matrix.

Returns true if this.raw is the same as the identity matrix with which it was initialized. Note that this only compares literal numeric values. If the members of the array are functions, this method will return false even if the end result is the identity matrix.

This is a convenience method for applying a rotation to the current Matrix. Values are in degrees, and if y and z are undefined, the value of x will be used for both of them.

This is a convenience method for applying a scale transformation to the current Matrix. If y and z are undefined, the value of x will be used for both of them.

This is a convenience method for applying skew transformations to the current Matrix. As with the similar convenience form in the constructor, the pairs of axes are passed as members of the pairs object, e.g.

This is a convenience method for applying a translation to the current Matrix. If y and z are undefined, the value of x will be used for both of them.

Returns the SDL representation of the matrix as a string, indented by the optional number of tab stops. Unlike most other toSDL methods, this one always succeeds because the constructor either requires or supplies all of the mandatory values.

Given another Matrix, that, returns a new Matrix that is the product of this × that.

Given a VectorXYZ, point, returns a new VectorXYZ which has been transformed by the matrix.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

Geometric Primitives

Primitive

The Primitive type is the base class for all of the other geometric primitives. Unless you're implementing a new primitive, perhaps for one of the experimental forks of POV-Ray like MegaPOV, you don't need to worry about its internals, but you do need to be familiar with the public attributes and methods it shares with all of its subclasses.

Transformations

Two of those attributes, baseTransform and transform, are important enough to discuss outside of the attributes table, below. In order to support several significant features now and in the future, CephaloPOV distinguishes between an initial transformation that is effectively part of the definition of an object and subsequent transformations applied to it. That initial transformation is the baseTransform, and the subsequent transformations are combined mathematically in the transform attribute.

When a Primitive is output to SDL, the current value of its transform attribute is included in the object definition. The baseTransform is kept internal to CephaloPOV to help with geometric queries and the scene graph system. Most of the time, you won't have to do anything more than set the baseTransform, though it can be useful in user code in snapshot mode, as we will see.

The easiest way and clearest way to establish the baseTransform is simply to assign it:

If you don't set baseTransform explicitly, setting transform will set it at the same time. Naturally, if you are defining an object that doesn't change from frame to frame and its initial parameters are fine without any transformations at all, you don't have to bother with either transform attribute.

Each time thereafter that you set transform, the supplied Matrix is multiplied by the existing transform value. Because of the way matrix multiplication works, this will effectively add the new transformation to the transformations that have already been applied. If you want to start over fresh with the baseTransform value, just call the resetTransform method.

The main purpose of all of this behind-the-scenes plumbing is to provide the necessary basis for higher-level features like the not yet implemented scene graph, and you don't have to worry about it much in your own user programs. One exception to this is if you are using snapshot mode, where multiple output objects can be created using a single primitive object and repeatedly setting transform and then calling baseTransform.

Like most other object attributes in CephaloPOV, transformations can be either the necessary type (in this case Matrix), or a JavaScript function returning a Matrix, or SDL code supplied as a string with the usual "&" prefix. Barring bugs, all three are perfectly fine, but transform is frequently the subject of matrix multiplication at the JavaScript level. How does this work?

A numeric Matrix performs exactly as expected. SDL strings will halt the program with an error. If transform is a JavaScript function returning a Matrix, it will be replaced with its return value and then altered accordingly. The same applies to JavaScript functions as individual matrix elements. This is one of the few places that the difference between the three execution scopes—CephaloPOV, the user program, and POV-Ray—is so important to understand clearly. The power and flexibility of the approach is great, but you can expect a little eye-crossing confusion at first.

Attributes

Methods

Restores the object's current transform to the value of its baseTransform.

This is a convenience method for applying a rotation to the current object. Values are in degrees, and if y and z are undefined, the value of x will be used for both of them.

This is a convenience method for applying a scale transformation to the current object. If y and z are undefined, the value of x will be used for both of them.

This is a convenience method for applying skew transformations to the current object. As with the similar convenience form in the constructor, the pairs of axes are passed as members of the pairs object, e.g.

If cpov.settings.snapshotMode is true, this method sends the output of toSDL to the snapshot output buffer, where it will remain until cpov.outputFrame is called.

Returns the SDL representation of the Primitive as a string, indented by the optional number of tab stops. User programs will seldom if ever call this directly, but it is overridden and called by the toSDL methods in the subclasses. Those subclass methods will emit a fatal error message if any mandatory attributes are not specified, but the Primitive base class has no mandatory attributes, so this call will always succed.

This is a convenience method for applying a translation to the current object. If y and z are undefined, the value of x will be used for both of them.

This is a convenience function which takes an object full of key/value pairs and sets several attributes at the same time, much like the constructor, which avoids having to set them individually. The following are equivalent:

BicubicPatch

The BicubicPatch type is a curved surface defined by a 4 × 4 array of VectorXYZ control points which are interpolated behind the scenes using Bezier splines and converted to a mesh of triangles. The number of triangles used along the u- and v-axes are defined by uSteps and vSteps. var obj = new BicubicPatch({ type: 0, flatness: 0.01, uSteps: 4, vSteps: 4, points: [ [0, 2, 0], [0, 0, 1], [0, 0, 2], [0, -2, 3], [1, 0, 0], [1, 0, 1], [1, 0, 2], [1, 0, 3], [2, 0, 0], [2, 0, 1], [2, 0, 2], [2, 0, 3], [3, 2, 0], [3, 0, 1], [3, 0, 2], [3, -2, 3] ] });

Attributes

Blob

The Blob type is an isosurface of scalar fields produced by points and lines represented in the components array by Sphere and Cylinder objects. What this means in practice is that each object has a field strength that starts at the center of the object and drops to zero at its radius. The surface of the blob is wherever the overlapping fields have a value equal to the blob's threshold value, which defaults to 1.0. The effect is a smooth surface like drops and strings of honey. This makes the Blob an excellent tool for building smooth, organic shapes. In the simple example here, a Blob composed of three Sphere objects forms a lumpy diagonal line through the demo stage space. var obj = new Blob({ components: [ new Sphere({ center: [-1.5, -1.5, -1.5], radius: 2, strength: 4 }), new Sphere({ center: [ 0, 0, 0], radius: 2, strength: 4 }), new Sphere({ center: [ 1.5, 1.5, 1.5], radius: 2, strength: 4 }), ] });

Attributes

Box
The Box type is exactly what it sounds like: a rectangular box. It is defined by the coordinates of two diagonally opposite corners, corner1 and corner2. Its sides are orthogonal to the axes, so other orientations will require applying a transformation. The example at right was created by the following code: var obj = new Box({ corner1: [2, 2, 2], corner2: [-2, -2, -2] });

Attributes

Camera

Camera objects provide a point of view in the scene. There can be many in a scene, but only one can have its active flag set to true when a frame is output. POV-Ray will happily accept multiple cameras, but it only uses the last one defined in the .pov file. In keeping with CephaloPOV's philosophy of catching errors early so you don't have to puzzle over a broken SDL script, only the first active camera is output and a warning is issued for the others.

Unlike a LightSource, POV-Ray will for some reason not allow cameras to be part of CSG operations, hence Camera.csgOperand is always false. Because it is often extremely useful to attach a camera to an object and doing so manually would involve a lot of extra code for user programs, CephaloPOV's Primitive class includes a satellites attribute that provides an easy workaround. A simple array of other Primitive objects, transformations applied to the parent are applied to each of the satellite objects, keeping them in the same relationship to the parent as when they were defined. Technically, any Primitive can be used as a satellite, but you're probably best off sticking to Union or Merge CSG objects, as they are more robust.

Attributes

Methods

TODO

Cone

The Cone type is deceptively simple. At a minimum, you must specify a basePoint and a capPoint along with their respective radii. For the result to be a cone, one of the radii must be zero, but non-zero values will produce a frustum, i.e., a truncated cone. You can also remove the endcaps and create a hollow cone by setting open to true. The example at right was created by the following code: var obj = new Cone({ basePoint: [0, -2, 0], baseRadius: 2, capPoint: [0, 2, 0], capRadius: 0 });

Attributes

Cubic

A Cubic is a third-order polynomial surface. It has a single required attribute like the rest of the polynomial types, coefficients, which is an array of 20 floats.

Attributes

Cylinder

The Cylinder type produces a solid cylinder by default and defined by the coordinates of the centers of its two circular ends, basePoint and capPoint, plus the radius of both. If the open attribute is true, the end caps are omitted and the interior is hollow, leaving an infinitely thin tube. If it is being used as a component in a Blob, the strength attribute can be used to assign a field strength to the cylinder. The following code produces the example at right: var obj = new Cylinder({ basePoint: [0, -2, 0], capPoint: [0, 2, 0], radius: 2, });

Attributes

Difference

The Difference type is one of the four CSG operations. It has two required attributes. The positiveComponent is a single object (which may be another composite CSG object) from which the array of objects in negativeComponents is subtracted. In this case, one sphere has been subtracted from another, producing a sphere with a dish-shaped depression in one side. var obj1 = new Sphere({ center: [1,0,-2], radius: 1.5 }); var obj2 = new Sphere({ center: [3,0,-1], radius: 1.5 }); var diff = new Difference({ positiveComponent: obj1, negativeComponents: [obj2] });

Attributes

Disc
The Disc type is a two-dimensional circular disc defined by its center, radius, and normal. As in the example below, it is possible to turn it into a washer-like ring by specifying a non-zero holeRadius. var obj = new Disc({ center: [0, 0, 0], radius: 2, holeRadius: 1, normal: [0, 1, 0] });

Attributes

HeightField

A HeightField takes a bitmapped graphics file and converts it into a triangle mesh in which the height of each point is determined by either the intensity of the corresponding pixel or, for indexed graphics, its index number. It is frequently used for creating landscapes. The resulting mesh fits into a unit cube. The optional waterLevel attribute, set to a value in the unit interval (0.0 - 1.0), progressively hides a portion of the mesh to simulate water. (It does not provide a water plane; you will have to do that yourself.) A waterLevel value of 0.0 reveals the entire mesh, while a value of 1.0 hides all of it; intermediate values hide only part of it. For complete details on the graphics formats accepted, see the POV-Ray documentation. The example here uses a 16-bit greyscale PNG file. var obj = new HeightField({ source: "hf_demo.png", waterLevel: 0.4, smooth: true, texture: yellow }); var xform = new Matrix("translate", -0.5, -0.5, -0.5); obj.transform = xform.xMatrix(new Matrix("scale", 6, 3, 6));

Attributes

Intersection

The Intersection type is one of the four CSG operations. Like all of the CSG operations other than Difference, it has a single mandatory attribute, components, which is an array of objects. The result is their set-theoretical intersection, i.e., the space in which all of the components overlap. In the example, we have taken the intersection of two overlapping spheres, yielding an object shaped like the lens of a magnifying glass. var obj1 = new Sphere({ center: [1,0,-2], radius: 1.5 }); var obj2 = new Sphere({ center: [3,0,-1], radius: 1.5 }); var intersection = new Intersection({ components: [ obj1, obj2 ] });

Attributes

IsoSurface

Short of the dubious goal of writing a JavaScript-to-SDL compiler, complete independence from POV-Ray's Scene Description Language is not possible in a few cases. The IsoSurface object is one of these because its sole required attribute, source, is a function or functions written in SDL. It's worth the effort of understanding, however, because the definition of isosurfaces is one of POV-Ray's most powerful features. For complete details, see the POV-Ray docs. In this example, we're just grabbing an example from the POV-Ray docs to serve as the source attribute. Don't forget to include the leading '&' that tells CephaloPOV that it's getting SDL code instead of an ordinary string. var obj = new IsoSurface({ source: "&function{fn_A(x,y,z) + " + "pow(Blob_Threshold,(fn_B(x,y,z) + Strength))}" });

Attributes

JuliaFractal

The JuliaFractal is a three-dimensional slice of a four-dimensional Julia fractal set. See the POV-Ray docs for a little more detail. The CephaloPOV interface follows the POV-Ray model quite closely, the major difference being that POV-Ray's anonymous algebra type and function type parameters are combined in type. var obj = new JuliaFractal({ juliaParam: [-0.083, 0.0, -0.83, -0.025], type: "quaternion:sqr", maxIter: 8, precision: 15 });

Attributes

Lathe

The Lathe object is a surface of revolution created by sweeping a spline around the y-axis, centered at the origin. The resulting object is solid, but the spline will not produce a closed curve unless the first and last points are the same. A Lathe is much more flexible than the other surface of revolution object, Sor, but it is also substantially slower to render. var obj = new Lathe({ points: [ [0, -1.2], [1, -1.2], [1, -0.8], [0.8, -0.6], [0.8, -0.4], [1, -0.4], [1, -0.2], [0.8, -0.2], [0.8, 0], [1, 0], [1, 0.2], [0.8, 0.2], [0.6, 0.8], [0.6, 1.2], [0.8, 1.2], [0.8, 1.4], [0, 1.4] ], type: "linearSpline" });

Attributes

LightSource

TODO

Attributes

Merge

The Merge type is one of the four CSG operations. Like all of the CSG operations other than Difference, it has a single mandatory attribute, components, which is an array of objects. The result is their set-theoretical union, which is different from the original ad hoc collection of objects in that it can be treated as a single object and tranformed and textured as a whole, as well as participating in further CSG operations. A Merge differs from the otherwise identical Union by eliminating the hidden inner surfaces. This doesn't matter with opaque objects, of course, but it is often useful when creating transparent or translucent objects. In the example, we have merged two spheres, resulting in a single object that looks, um, exactly like two spheres. var obj1 = new Sphere({ center: [1,0,-2], radius: 1.5 }); var obj2 = new Sphere({ center: [3,0,-1], radius: 1.5 }); var merge = new Merge({ components: [ obj1, obj2 ] });

Attributes

Mesh
TODO var obj = new PlaceholderObj({ // TODO });

Attributes

Ovus

The Ovus type is one of POV-Ray's more interesting and versatile geometric primitives. It consists of two spheres defined by bottomRadius and topRadius such that the center of the top sphere is positioned on the top of the bottom sphere, and then a smooth curved surface connects the two. The center of the bottom sphere is at the origin, and the centers of both spheres are aligned along the y-axis. In the example code below, the result is the egg-like shape to the right, but a wide variety of other shapes can be constructed with it. var obj = new Ovus({ bottomRadius: 2, topRadius: 1 });

Attributes

Parametric

Along with IsoSurface, the Parametric type is one of the places where CephaloPOV cannot shield you from the POV-Ray Scene Description Language, or at least a subset of it. However, also like IsoSurface, the Parametric type is one of POV-Ray's most powerful features, so it's well worth the effort of understanding the POV-Ray docs and a few online tutorials unless you're especially math-averse. (And if so, do you know where you are?) The short version is that Parametric objects are hollow surfaces defined by three functions that map the UV-plane to explicit xyz-coordinates whereas IsoSurface objects are solid and have surfaces implicitly defined by a single function yielding a potential field. Ergo, in place of the single source attribute of the IsoSurface, a Parametric has an attribute for each of the three axes, funcX, funcY, and funcZ. var p2 = 2 * Math.PI; var obj = new Parametric({ funcX: "&function { 1.0 * (1 - 0.5 * v / pi) " + "* sin(5 * v + 0.5 *pi) " + "* (1 - cos(u)) + 0.2 * sin(5 * v + 0.5 * pi) }", funcY: "&function { 8 * 0.5 * v / pi + 1.0 " + "* (1 - 0.5 * v / pi) * sin(u) }", funcZ: "&function { 1.0 * (1 - 0.5 * v / pi) " + "* cos(5 * v + 0.5 * pi) " + * (1 - cos(u)) + 0.2 * cos(5 * v + 0.5 * pi) }", uv1: [0, 0], uv2: [p2, p2], accuracy: 0.0035, precomputeDepth: 18, precomputeX: true, precomputeY: true, precomputeZ: true, maxGradient: 10, containedBy: new Box({ corner1: [-p2, -p2, -p2], corner2: [p2, 8/3 *p2, p2], }), }); obj.transform = new Matrix("scale", 0.4, 0.4, 0.4); obj.transform = new Matrix("rotate", 0, 90, 0);

Attributes

Plane

Arguably POV-Ray's simplest primitive, the Plane is an infinite solid dividing all space into two halves. It is defined by a distance from the origin and a normal which determines the orientation of its surface. It provides a convenient infinite ground plane, of course, but because it creates a solid half-surface, you can use a CSG Intersection of planes to create complex shapes like solid polyhedra. In the example below, the plane is oriented perpendicularly to the y-axis at the origin. Its infinite extent is amusingly clear in the rendering to the right, where our standard demonstration stage looks like it has been caught in a flood! var obj = new Plane({ distance: 0, normal: [0, 1, 0] });

Attributes

Poly

The Poly type offers a generic interface to create polynomial surfaces of orders 2 to 35. You must specify the order of the polynomial and then supply its coefficients, the number of which depends on the order: n = ((order + 1) * (order + 2) * (order + 3)) / 6; (CephaloPOV will helpfully throw a fatal error if you get the number of coefficients wrong.) The example below, adapted from POV-Ray's shapesq.inc file, is a variant of a lemniscate. var obj = new Poly({ order: 6, coefficients: [ 4, 0, 0, 0, 0, 0, 0, 0, 0, -4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0 ], texture: yellow }); obj.transform = new Matrix("scale", 2, 2, 2);

Attributes

Polygon

Another versatile two-dimensional primitive, the Polygon type is defined by it's sole points parameter, which is an array of VectorXY points listing the vertices of an arbitrary polygon on the XY-plane. For a simple polygon, a line will automatically connect the first and last points. If the first point of the polygon is repeated, subsequent points create an additional polygon which, if it is enclosed in the first (or another) polygon, defines a hole in it. In the example code below, two rectangles are defined with the second being a hole in the first. var obj = new Polygon({ points: [[-2, 2], [2, 2], [2, -2], [-2, -2], [-2, 2], [-1, 1], [1, 1], [1, -1], [-1, -1], [-1, 1]], });

Attributes

Polynomial

The Polynomial type is another arbitrary polynomial shape object that provides an alternative to the Poly type, and like it, it must have an order in the range 2–35. The coefficients are encoded in an array of VectorXYZW where the x, y, and z attributes signify the powers of the respective indeterminates and w is repurposed to contain the coefficient. As noted in the description of Poly, the order determines the number of coefficients thus: n = ((order + 1) * (order + 2) * (order + 3)) / 6; In the example shown, a sphere is produced by a second-order polynomial. var obj = new Polynomial({ order: 2, coefficients: [ [2, 0, 0, 1], [0, 2, 0, 1], [0, 0, 2, 1], [0, 0, 0, -1] ] });

Attributes

Prism

The Prism type is the three-dimensional analogue of the Polygon. It sweeps the shape defined by the array of VectorXY in the points parameter along the y-axis from height1 to height2. The points may define multiple sub-polygons provided that each polygon is closed by repeating the first point as the last. Unlike Polygon.points, Prism.points may specify more than just simple linear splines depending on the value of type. The example below uses the same points argument as the example for the Polygon. var obj = new Polygon({ height1: -2, height2: 2, type: "linearSpline", points: [[-2, 2], [2, 2], [2, -2], [-2, -2], [-2, 2], [-1, 1], [1, 1], [1, -1], [-1, -1], [-1, 1]], });

Attributes

Quadric
The Quadric type is an optimized second-order polynomial shape. Its sole required attribute is coefficients, an array of 10 floats. The example shown is an infinite hyperboloid aligned with the y-axis. var obj = new Quadric({ coefficients: [ 1, -1, 1, 0, 0, 0, 0, 0, 0, -1 ], texture: yellow });

Attributes

Quartic

The Quartic type is an optimized fourth-order polynomial shape. Its sole required attribute is coefficients, an array of 35 floats. The example here is a torus, albeit one that renders more slowly than the optimized, dedicated Torus type. var obj = new Quartic({ coefficients: [ 1, 0, 0, 0, 2, 0, 0, 2, 0, -104, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 2, 0, 56, 0, 0, 0, 0, 1, 0, -104, 0, 784 ], texture: yellow }); obj.transform = new Matrix("scale", 0.2, 0.2, 0.2);

Attributes

Sor

The Sor object, in addition to being an example of how camelCase breaks down when forced to ingest acronyms, is a simpler and faster form of a surface of revolution than the Lathe object. It supports only a single type of smoothly interpolated curve which cannot be closed and can have only a single radius (x) value at any given point (y), i.e., it's a normal mathematical function. However, unlike a Lathe, a Sor has an open attribute which, if true, eliminates the normal endcaps and yields a hollow shape. var obj = new Sor({ points: [ [0, -1.4], [0, -1.3], [1, -1.2], [1, -0.8], [0.8, -0.6], [0.8, -0.5], [1, -0.4], [1, -0.3], [0.8, -0.2], [0.8, 0.1], [1, 0.2], [1, 0.3], [0.8, 0.4], [0.6, 0.8], [0.6, 1.2], [0.8, 1.3], [0.8, 1.4], [0, 1.5], [0, 1.6] ] });

Attributes

Sphere
The Sphere is defined by the coordinates of its center and the measure of its radius. The example at right was created by the following code: var obj = new Sphere({ center: [0, 0, 0], radius: 2 }); The optional strength parameter does nothing with an independent Sphere, but when the object is part of a Blob, it sets the field strength.

Attributes

SphereSweep

A SphereSweep is a shape consisting of the space occupied by a sphere moving along a spline. The radius of the sphere can vary over time. It is defined by an array of spheres, with a minimum of two for a linear spline or four spheres for a bezier spline or a cubic spline. For the sake of brevity, the example consists of a linear spline arranged in a rectangle with two different sizes of spheres acting as control points, but you can construct arbitrarily complicated shapes with a SphereSweep. var obj = new SphereSweep({ spheres: [ new Sphere({ center: [-1, 1, -1], radius: 0.25 }), new Sphere({ center: [-1, 1, 1], radius: 0.5 }), new Sphere({ center: [1, -1, 1], radius: 0.25 }), new Sphere({ center: [1, -1, -1], radius: 0.5 }), new Sphere({ center: [-1, 1, -1], radius: 0.25 }), ], type: "linearSpline" });

Attributes

Superellipsoid

The Superellipsoid type implements what is more properly known as a superquadric ellipsoid whose shape can vary from a cube with rounded edges to fat, egg-like cylinders. It is defined solely by two float parameters, e and n, the so-called east-west and north-south exponents, respectively. It occupies roughly the same space as a Box with corners at [1, 1, 1] and [-1, -1, -1]. As the example code and rendering indicate, when e and n have the same value, the result is a cube with rounded edges. When both values reach 1.0, the result is equivalent to a unit sphere. var obj = new Superellipsoid({ e: 0.25, n: 0.25 });

Attributes

Text

The Text type is very similar to the Prism type, the main difference being that instead of specifying a spline yourself, you hand it a string and the pathname of a TrueType font or a TrueType collection from which the first font will be used. Fonts, even professionally-designed ones, vary in their obedience to conventions, so some experimentation is often needed. In most cases, individual characters will be one unit high. The extruded text will begin at the origin and run in the +x direction along the x-axis. The front of the text will be parallel to the xy-plane and the extrusion will go in the +z direction. var obj = new Text({ displayText: "CPOV", font: "BebasNeueBold.ttf", fontType: "ttf", thickness: 0.25, offset: 0 }); obj.transform = new Matrix("scale", 2, 2, 2); obj.transform = new Matrix("translate", 0, 0, -1);

Attributes

Torus

The Torus type specifies a torus with its major and minor radii. If you think of a torus as the surface described by a smaller two-dimensional ring swept perpendicularly to a larger ring, the majorRadius is the radius of the larger ring, and the minorRadius is the radius of the smaller ring. The example code and rendering demonstrates a Torus with a minor radius of 0.5 units and a major radius of 2 units. var obj = new Torus({ minorRadius: 0.5, majorRadius: 2 });

Attributes

Triangle

The Triangle type describes a triangular patch that can be used independently or as part of a mesh. There are two kinds of triangles in POV-Ray, triangle and smooth_triangle, and both are subsumed in CephaloPOV's Triangle. A (plain) triangle has only three required attributes, corner1, corner2, and corner3, all VectorXYZ objects with an obvious purpose. A smooth triangle takes four more attributes. The first is smooth, which must be true, in addition to which normal1, normal2, and normal3 must be set. This enables the use of Phong shading. If smooth is false, the triangle will be output as a plain triangle. Toggling between the two can be useful for speeding up preview renders or effects in animations. var obj = new Triangle({ corner1: [ -1, -1, -1 ], corner2: [ 1, -1, -1 ], corner3: [ 0, 1, 1 ], texture: yellow });

Attributes

Union

The Union type is one of the four CSG operations. Like all of the CSG operations other than Difference, it has a single mandatory attribute, components, which is an array of objects. The result is their set-theoretical union, which is different from the original ad hoc collection of objects in that it can be treated as a single object and tranformed and textured as a whole, as well as participating in further CSG operations. A Union differs from the otherwise identical Merge by retaining the hidden inner surfaces. This doesn't matter with opaque objects, of course, but it is often useful when creating transparent or translucent objects. In the example, we have merged two spheres, resulting in a single object that looks, um, exactly like two spheres. var obj1 = new Sphere({ center: [1,0,-2], radius: 1.5 }); var obj2 = new Sphere({ center: [3,0,-1], radius: 1.5 }); var union = new Union({ components: [ obj1, obj2 ] });

Attributes

Texture Classes

POV-Ray's texture system, which governs the appearance of the surface of objects, is more complicated than the objects themselves. It's not especially hard to use; there's just a lot of it. CephaloPOV attempts to wrap it in as straightforward a set of JavaScript classes as possible, but there's no hiding the underlying complexity. Moreover, as with the geometric primitives, there are some features of the texture system that are impossible to access without resorting to SDL. That said, CephaloPOV's wrappers capture well over 95% of its functionality and offers escape routes into SDL for the remaining 5%.

Optional Libraries

CephaloPOV includes a small but growing number of optional standard libraries, where "standard" just means they ship with CephaloPOV and there's a special method to require them using handy aliases:

Some of the libraries are ports of POV-Ray include files to their JavaScript equivalents. These are generally loaded using their POV-Ray names, like colors.inc. Others provide useful functionality like Robert Penner's easing functions.

colors.inc

This is a straight port of the color names and RGB values in POV-Ray's standard include file, colors.inc.

Importing this library makes the following color values available:

easingFuncs

The easingFuncs library makes Robert Penner's easing functions available for use in animations.

The following diagram illustrates the speed-over-time curves of the easing functions:

Methods

All of the easing functions take the same four arguments: currentTime, startVal, change, and duration. (A few of them take an optional fifth argument, s, which is a tuning value.) The currentTime argument specifies the current time in whatever unit you're using, e.g., frames, seconds, etc., while duration specifies the total length of the easing sequence. The initial value of the property being eased is startVal, and change is the amount by which that value changes over the course of the animation.

For example, if you want to animate some object's x value from 0 to 50 over the course of thirty frames using easeInBounce, you might try something like this:

Internals: Hacking CephaloPOV

This section, it will surprise absolutely no one, started as a simple reference to help me get through the first version and be able to tolerate the fairly frequent and sometimes lengthy interruptions during which code you wrote with your own hands becomes someone else's code. The same information serves well as a guide for other developers, so I'm making an effort to keep it up to date and flesh it out. That said, you know how far I am from completing the end-user docs? I am even further away from finishing the developer docs.

In the meantime, feel free to ask questions on the development mailing list, and if you feel like adding to the documentation (hint, hint) then just submit a pull request.

Platform Details

CephaloPOV is developed and tested using something close to the latest LTS release of Node. As of 2021-08-08, this is version 14.17.4. I am making no commitment to maintain compatibility with older versions of Node, but if you encounter a regression with different versions of Node, I will be happy to see if there's a way to fix it without being bound to something other than the latest Node version. I will be even happier if you figure it out and submit a patch.

For various practical reasons, my personal development machine is relatively recent desktop machine running Windows 10 along with Cygwin. The main CephaloPOV program is tested running from the Windows command prompt, as well as Cygwin's version of bash and whatever reasonably current Linux distribution I happen to have handy at the time. If you're going to work on CephaloPOV, you probably want to do it under Linux or Windows+Cygwin, as the build and test scripts are neither tested nor maintained for the Windows shell. As with the main program, I am happy to look into platform compatibility issues, but grinding out MS-DOS .bat files to maintain parity with the corresponding bash scripts is not going to be a high priority for me.

In general, I am trying very hard to avoid doing anything that would require platform-specific code, mainly because I don't want to be responsible for maintaining a port to platforms I do not have ready access to. I am not opposed to someone contributing platform-specific features, but only if the contributors are willing to maintain their contributions.

The File Manifest

Only the important files are listed here. Things like individual graphics files for the documentation and generic infrastructure like package.json are omitted.

The Build Process

The build process for CephaloPOV is a bit eccentric. It arose during the process of settling on the current architecture, which was the fourth attempt at doing so. I was determined to get it right and not settle on a sub-optimal solution simply because of the effort that went into building it or the effort that would be required to replace it with something else.

Consequently, it is a data-driven code generation process. Classes are defined in a number of definition files, e.g., objDef.js, PrimitiveDef.js, etc., and this drives the creation of the main code file, classes.js and parts of the documentation. Earlier versions were purely declarative, but that resulted in an apparently endless process of coding exceptions and edge cases, so the current version uses automatic code generation where it is convenient and clear, but it grabs named blocks of manual code from snippets.js where that is easier.

It should be noted that both the definition files and their processor, build.js, may be eliminated once CephaloPOV is complete and has been stable for a while. Persons who want to fork CephaloPOV and go in their own direction might want to at least consider doing away with it now, but for the time being, modifying the program means dealing with the code generation system, so it is documented here.

build.js

As noted above, build.js manages the build process. It's an ordinary command line JavaScript program that you will find in CephaloPOV's root directory. Pass it the -h switch for usage instructions:

The first two options, --classes and --docs, are the only essential ones. The --classes switch will rebuild classes.js by reading from the various *Def.js files and snippets.js. In so doing, classes.js is overwritten and replaced. The --docs switch rebuilds parts of the documentation in docs/index.html by replacing the HTML in specially marked sections (see the docHumper function for more details). Text outside of those sections is left unaltered.

The other two options, --snippets and --objlist, are convenience tools. The --snippets switch just reads snippets.js and writes it back out to snippets.new.js with a little bit of formatting cleanup. The --objlist switch simply outputs a list of generated classes, which of course excludes classes that are entirely manually defined, such as Matrix.

It's only fair to warn you that while build.js is not a large program, parts of it are pretty hairy, so tread with caution if you want to modify it.

The *Def.js Definition Files

Each of the definition files consists of a JavaScript object or objects defining the parameters of a generated class and specifying the names of chunks from snippets.js to fill in specialized functionality. The format of the definition objects is pretty simple and not at all hard to figure out even without documentation, but we'll walk through a (hypothetical) object that exercises all of the features at once.

At the top level of each object are some or all of the following members:

The superclass member defines the parent class, if any. For base classes, this can be omitted. The desc member holds a human-readable description of the class for the docs. (This isn't actually in use yet, but it eventually will be. In the meantime, it's okay to leave it false.)

If you look through the generated code in classes.js, you'll notice that almost all of the constructor methods take a single argument, options. This is the default produced when conArgs is false. Should you wish to override this behavior, conArgs can be set to a string which will be placed in the constructor signature.

The conBlock member can be a string containing the name of a snippet to insert into the constructor method after the declaration of the mutable members (for which, see below). It is usually false.

The snippets member is either false or it is an array of strings containing the names of snippets to include in the class. They are inserted after the generated methods in the order given.

As noted in the user documentation, all primitive types have a set of immutable (i.e., read-only) attributes. These are specified as an object whose keys are the desired attribute names and values. These are converted into accessor functions during code generation.

The final and largest part of the class definition appears in the mutable member, which defines the mutable attributes of the class and/or specifies a snippet to handle them. They look something like this:

The name member corresponds to the name of the accessor methods. Their internal representations are stored with an underscore prefix, e.g., _name, because JavaScript doesn't yet support actual private object members. These are largely initialized to null in the constructor. The req member is a boolean which determines whether or not the member must be initialized prior to being output as SDL code.

Validation at assignment time is performed by the code snippet in valid, which on failure outputs the error message defined in err. The description of the member in the documentation is provided by desc, and the contents of tname are used in the docs to specify the type of the class member.

There are a few additional members that are not shown in the example above. In a few cases, the autogenerated accessor methods are inadequate, so custom specifies the name of a snippet to use instead. For mutable members that are managed by CephaloPOV, like the parent members of objects contained by other objects, setting dperm to "RO" will make them read-only to user programs. Attributes containing other objects will also have a child member with a value of either "scalar" or "array", which tells CephaloPOV that those objects' parent attributes must be updated upon assignment.

snippets.js

Everything sufficiently complex or specialized that it is easier to code manually than to generate lives in snippets.js. The organization of the file is extremely simple. Each code block begins with a specially formatted comment to define its name, and the associated code continues until the next special comment or the end of the file, whichever comes first. The special comments look like this:

The comment must begin in the first column, and the spaces between the slashes and the name are required. The name itself cannot contain spaces. Everything following the trailing slashes is ignored; the dashed line is just for easy readability.

And that's it for snippets.js: it's just a collection of named chunks of code which are inserted in the generated classes as directed by the snippets member of the class definitions in the *Def.js files.

In case you're wondering about motivations, you should know that the first version attempted to automate nearly everything, but then I ended up spending more and more time maintaining and extending a version of build.js that was increasingly resembling a compiler. The current version mostly handles the tedious boilerplate involved in wrapping POV-Ray's collection of primitives into JavaScript classes, making it easy to update and debug those portions. Everything else ends up in snippets.js, including the occasional entire class definition, as with Matrix.

Inside the cpov Object

Nearly everything other than class definitions and user code lives in the global cpov object, a singleton which is initialized in cephalopov.js.

Data

TODO

Methods

Because most of the code in CephaloPOV lives in classes, the cpov object's methods consist mainly of small generic data validation, data conversion, and odd utility functions. The validation and conversion methods are particularly important because they are used throughout the various classes to implement CephaloPOV's type system, so it is worth taking the time to familiarize yourself with them.

Used in error messages and the auto-generated parts of the documentation, this function takes an array of strings and returns a string in which they are delimited by commas and the conjunction "or". For example, ["one", "two", "three"] becomes "one, two, or three".

Setter methods in CephaloPOV objects that accept types VectorXY, VectorUV, VectorXYZ, VectorXYZW, or Color will also accept bare arrays just like the constructors for those classes. This is not coincidentally accomplished by passing val to the constructor for type and returning the result. Validation of val is left to the class' constructor and setter methods.

This is just the array version of cpov.convertToVector, where val is an array of numeric arrays instead of a single array. Returns the an array of objects of the specified type.

Converts the value of deg from degrees to radians and returns the result.

When called by the user program, this method terminates the animation loop. If a frame is in progress when it is called, it will not be output, so it is normally called after file output.

Outputs an error message using pretty colors if supported by the terminal. The level argument may be one of "fatal", "warn", "info", or "debug". If level is "fatal", the program terminates immediately unless cpov.settings.debug is greater than 1. (This is useful for debugging when working on CephaloPOV itself.) All other error levels simply emit an error message. This will appear on the terminal for "warn", "info", and "debug" at cpov.verbosity levels of 1, 2, and 3, respectively. In all cases, the error will also be written to cpov.settings.debugLog if initialized.

The error message is prefixed with the location where the error occurred, usually a class and method name, and the object serial and id, if any, are appended to the end of the line.

Takes a block of text in the form of a single string with embedded newlines and prefaces each line with the specified number of tab stops, returning the result. This function is heavily used in code generation.

Returns a boolean indicating whether object val is an instance of classname.

Standard initialization routine for most objects. Attempts to assign the values in vals, a simple JavaScript Object to the CephaloPOV object obj. Attributes that do not exist in obj will be ignored, and the setter methods of obj may throw a fatal error if the values fail whatever validation is applied to them. This routine is used for objects without an explicitly defined conBlock.

Returns true if val is an array of objects of any class inheriting from base class classname with min to max elements, false otherwise.

Returns true if val is an array of objects of class classname with min to max elements, false otherwise.

Returns true if val is an array of floats (i.e., type Number) with min to max elements, false otherwise.

Returns true if val is an array of integers with min to max elements, false otherwise. See cpov.isInt for what constitutes an integer in JavaScript's int-less type system.

Returns true if val is an array of non-empty Strings with min to max elements, false otherwise.

Returns true if val is an array of Strings with min to max elements, false otherwise.

Returns true if val is a member of a class inheriting from classname, false otherwise.

Returns true if min < val > max, false otherwise. See also cpov.isWithin.

Returns true if val is of type boolean, false otherwise. Note that it is the type of val that is being tested for, not its literal boolean value.

Returns true if val is of type String with a length of 1, false otherwise. JavaScript of course does not have a char type; we're just emulating one for POV-Ray's sake using single-character strings.

Returns true if val is a member of class classname, false otherwise.

Returns a boolean indicating whether val is a Number. It is so named because POV-Ray makes a distinction between floats and ints, and hopefully JavaScript will eventually be able to make the same distinction.

Returns a boolean indicating whether val is either a JavaScript function or an SDL function.

Returns true if val appears as an element of array, false otherwise.

Returns true if val is an integer, which for the purposes of JavaScript's lack of true integers means that the type of val is Number and it has no fractional part. Returns false otherwise.

Returns true if val is a JavaScript function, false otherwise.

Returns true if object[val] is defined, false otherwise.

Returns true if val is of type String and has a non-zero length, false otherwise.

Returns true if val is null, false otherwise.

Returns true if val is null, an object of type Function, or an SDL function, i.e., a string beginning with "&". In all other cases, it returns false.

Returns true if val is null or an object of type Function. In all other cases, including SDL function strings, it returns false.

Returns true if val is a power of two, false otherwise. As implemented, it only operates in the interval 2⁰–2⁶⁴.

Returns true if val is an SDL function, which for the purposes of CephaloPOV is a String beginning with an ampersand, i.e., "&".

Returns true if val is of type String, false otherwise.

CephaloPOV objects may contain a user-supplied GUID. This function tests whether val is already in use with another object. If not, it adds obj to cpov.idMap with val as an index and returns true. If val is already in use, it returns false instead.

In addition to optional user-supplied GUIDs (see cpov.isUnusedId, above), every CephaloPOV object has a unique serial number. This function tests whether val is already in use with another object. If not, it adds obj to cpov.serialMap with val as an index and returns true. If val is already in use, it returns false instead.

Takes a pattern name and returns a boolean indicating whether it is supported.

Returns true if min ≤ val ≥ max, false otherwise. See also cpov.isBetween.

This function converts the keys of obj to an array and wraps each element in single quotes before passing it to cpov.arrayToTextList to convert it into a comma-delimited string for use in the auto-generated parts of the documentation.

Takes a filename, which is currently always snippets.js, and parses it using specially formatted comments of the form

where the initial slash appears in the first column. The keyname is extracted and used to index the following text up to the next special comment. Although the examples you will see in snippets.js all have a line of trailing dashes, everything past the last slash is ignored. The spaces on either side of the keyname are mandatory, and the name itself cannot contain any whitespace.

The resulting object is returned and used for inserting the named blocks of code into the generated code, mostly in classes.js.

The cpov.outputFrame method exists for user programs to call whenever they have finished setting up a scene. It takes no arguments, its behavior being determined mostly by cpov.imageOptions and cpov.globalSettings. That behavior is already described in great detail in The Animation Cycles and will not be repeated here.

There is no return value. If any termination conditions are met, CephaloPOV will terminate with an exit code of 0.

Given a CephaloPOV object, returns a unique string consisting of the form #serial:id. If the object does not have an id, both it and the interstitial colon are omitted. This is appended to the error messages emitted by cpov.error.

CephaloPOV includes a number of optional libraries that are not automatically loaded at runtime. Each is identified by a mnemonic alias passed to cpov.requireOptLib, which in turn loads the library and returns it to the caller. Many of these are ports of POV-Ray include files to JavaScript identified by their original filename, e.g., colors.inc.

Takes a number, n, and returns it rounded to d decimal places.

This is the main animation loop which repeats, calling cpov.outputFrame() repeatedly until one of its termination conditions are met or the user program calls cpov.endAnimation.

One of the functions used in formatting generated code, both JavaScript and SDL, returns a string containing 4 * stops spaces. Do not submit a pull request changing this to tabs or other numbers of spaces, or I will curse you and your progeny.

Returns an array of objects that serve as stages or backdrops for geometric objects generated for tests and illustrations in the CephaloPOV documentation.

If type is given as "corner", the generated stage consists of three adjacent faces of a cube around one corner in the same configuration as a corner reflector. The faces are size units square and the axes run through the centroids of each face. If type is "triplane", then the stage takes the form of three translucent planes intersecting at the origin.

Cameras and lighting are included in the stage. It is assumed that the final image will have a 1:1 aspect ratio, so you will have to adjust the camera parameters, particularly camera.right, if you want a different aspect ratio.

It is highly likely that this function will be extended and changed in backwards-incompatible ways to serve the needs of documentation and testing, so if you want to use it outside of CephaloPOV itself, it's best to make your own copy of the function.

This function is used to calculate performance statistics. It takes a start and end time and a number of work units, and it returns an object containing the elapsed time in milliseconds and seconds and the average times per unit. (The units are usually frames.)

This function is used in the code generation process for classes.js and handles returning the value of an object appropriately depending on whether the value is a JavaScript function, an SDL snippet, or a general value.

Appendices

The appendices contain further details and discussions about CephaloPOV and ray tracing supplementary to the main text.

Matrices

SDL matrices are an abbreviated form of the entire matrix being used. The fourth column is invariant and therefore omitted from its SDL representation and inaccessible within CephaloPOV, but we show it below in grey for the math-curious. You don't have to know much about matrix math to use the Matrix class. Like SDL, CephaloPOV offers shortcuts to the individual transformations in the form of special arguments to the Matrix constructor and the apply method.

Translation, Scaling, and Skewing

Red elements determine scaling, blue elements determine translation, and green elements determine skewing. (The grey elements, as previously mentioned, are invariant and hidden in both POV-Ray and CephaloPOV.) Note that there are three elements for each axis when scaling and translating, but there are six elements for skewing, because skew transformations involve relationships between pairs of axes.

An important thing to notice here is that while the matrix elements that determine translation and skewing are 0 if no translation or skewing is to be done, the elements that define scaling must be 1 when no scaling is to be done, i.e., it's an identity element. Setting the scaling elements to zero will make the object disappear!

Another thing to notice about scaling is that negative values will reflect the object across the relevant axis. In the special case of 1, this will be a perfect mirror image; other values will stretch or squash the object.

Rotation

Rotation is a little more complicated because it requires the use of trigonometric functions. This is handled for you by the Matrix class' rotate constructor argument, but it's worth understanding in case you want to try doing the calculations yourself or trying variations to see what they do.

Since the values for rotations around the axes overlap, we'll omit the invariant fourth column and the translation row so we can cram all three rotation matrices into a single row. In this case, we'll color the rotation elements red, the single scale identity element blue, and everything else grey. If you're entirely innocent of trigonometry, know that cos and sin are the trigonometric functions cosine and sine, which are implemented in JavaScript as the Math.cos() and Math.sin() methods. The angle of rotation is conventionally represented by the Greek letter theta, θ, and is specified in radians, though POV-Ray and CephaloPOV expect you to use degrees instead and quietly translate degrees into radians for you.

Note the sign of the sine functions. These are specific to the left-handed coordinate system that POV-Ray uses. In a right-handed system, you'd reverse the signs.

If you want to know more, Jeff Lee's POV-Ray-specific tutorial is a good place to start, as are these course notes. To dig deeper than that—and there's a lot more you can do with matrices—the topic is covered in depth in 3D graphics and linear algebra textbooks. And don't be scared off: it's far more tedious than difficult. Choose a simple shape, try fiddling with different elements and different functions, and look at the results of a rendering.

Credits and Licenses

Every effort has been made to credit everyone whose code I used either directly, with modifications, or even as a model. I have also tried to credit everyone who provided technical instruction. If I missed anyone, please speak up.

The first round of applause goes to David K. Buck and all of the many subsequent developers who have built, maintained, and extended POV-Ray for the last three decades. A second round of applause goes to the folks who wrote POV-Ray's extensive documentation. Special thanks are also in order to Eric Haines, whose Ray-Tracing News kindled my interest in the field back when I was reading copies via gopher on a 3270 terminal at the University of Florida.

CephaloPOV itself is licensed under the BSD 2-clause license, which appears at the head of most of the files in the sources. For the npm dependencies, see package.json.

The easing equations used for animations originate with Robert Penner, who released them under the BSD 3-clause license. They were implemented in JavaScript for jQuery by George McGinley Smith, who subsequently released his code under the same license. It was from there that they were adapted (mostly by renaming variables and reformatting) for CephaloPOV.

Administrivia

TODO

Version 0.0.4

Version 0.0.5

Backlog

CephaloPOV Scene Graph

Master objects are defined relative to the origin. More precisely, the origin is their primary point of articulation. In each frame, they are transformed to their current frame-state.

Possibly, a relationship between A and B is stated in the form of B's point of articulation relative to some explicit or implicit point in A. In its most basic form, this would amount to free movement of B relative to its attachment point to A. PSII could provide a set of standard constraints, e.g., ball joint, hinge, track, etc., which could be built upon or supplanted by the user.

This suggests a separate assembly process for objects with moving parts, which means that ordinary native CSG objects can go ahead just fine. Converting them into master objects amounts to just positioning them appropriately relative to the origin after construction.

Changelog

Oh geez, not yet.