3.7.12 shapes.inc, shapes_old.inc, shapes2.inc, shapesq.inc

These files contain predefined shapes and shape-generation macros.

"shapes.inc" includes "shapes_old.inc" and contains many macros for working with objects, and for creating special objects, such as bevelled text, spherical height fields, and rounded shapes.

Many of the objects in "shapes_old.inc" are not very useful in the newer versions of POV-Ray, and are kept for backwards compatability with old scenes written for versions of POV-Ray that lacked primitives like cones, disks, planes, etc.

The file "shapes2.inc" contains some more useful shapes, including regular polyhedrons, and "shapesq.inc" contains several quartic and cubic shape definitions.

Some of the shapes in "shapesq.inc" would be much easier to generate, more flexible, and possibly faster rendering as isosurfaces, but are still useful for two reasons: backwards compatability, and the fact that isosurfaces are always finite.

3.7.12.1 shapes.inc

Isect(Pt, Dir, Obj, OPt) and IsectN(Pt, Dir, Obj, OPt, ONorm)
These macros are interfaces to the trace() function. Isect() only returns the intersection point, IsectN() returns the surface normal as well. These macros return the point and normal information through their parameters, and true or false depending on whether an intersection was found:
If an intersection is found, they return true and set OPt to the intersection point, and ONorm to the normal. Otherwise they return false, and do not modify OPt or ONorm.
Parameters:

Pt = The origin (starting point) of the ray.
Dir = The direction of the ray.
Obj = The object to test for intersection with.
OPt = A declared variable, the macro will set this to the intersection point.
ONorm = A declared variable, the macro will set this to the surface normal at the intersection point.

Extents(Obj, Min, Max). This macro is a shortcut for calling both min_extent() and max_extent() to get the corners of the bounding box of an object. It returns these values through the Min and Max parameters.
Parameters:

Obj = The object you are getting the extents of.
Min = A declared variable, the macro will set this to the min_extent of the object.
Max = A declared variable, the macro will set this to the max_extent of the object.

Center_Object(Object, Axis). A shortcut for using the Center_Trans() macro with an object.
Parameters:

Object = The object to be centered.
Axis = See Center_Trans() in the transforms.inc documentation.

Align_Object(Object, Axis, Pt). A shortcut for using the Align_Trans() macro with an object.
Parameters:

Object = The object to be aligned.
Axis = See Align_Trans() in the transforms.inc documentation.
Point = The point to which to align the bounding box of the object.

Bevelled_Text(Font, String, Cuts, BevelAng, BevelDepth, Depth, Offset, UseMerge). This macro attempts to "bevel" the front edges of a text object. It accomplishes this by making an intersection of multiple copies of the text object, each sheared in a different direction. The results are no perfect, but may be entirely acceptable for some purposes. Warning: the object generated may render considerably more slowly than an ordinary text object.
Parameters:

Font = A string specifying the font to use.
String = The text string the object is generated from.
Cuts = The number of intersections to use in bevelling the text. More cuts give smoother results, but take more memory and are slower rendering.
BevelAng = The angle of the bevelled edge.
BevelDepth = The thickness of the bevelled portion.
Depth = The total thickness of the resulting text object.
Offset = The offset parameter for the text object. The z value of this vector will be ignored, because the front faces of all the letters need to be coplanar for the bevelling to work.
UseMerge = Switch between merge (1) and union (0).

Text_Space(Font, String, Size, Spacing). Computes the width of a text string, including "white space", it returns the advance widths of all n letters. Text_Space gives the space a text, or a glyph, occupies in regard to its surroundings.
Parameters:

Font = A string specifying the font to use.
String = The text string the object is generated from.
Size = A scaling value.
Spacing = The amount of space to add between the characters.

Text_Width(Font, String, Size, Spacing). Computes the width of a text string, it returns the advance widths of the first n-1 letters, plus the glyph width of the last letter. Text_Width gives the "physical" width of the text and if you use only one letter the "fysical" width of one glyph.
Parameters:

Font = A string specifying the font to use.
String = The text string the object is generated from.
Size = A scaling value.
Spacing = The amount of space to add between the characters.

Align_Left, Align_Right, Align_Center. These constants are used by the Circle_Text() macro.

Circle_Text(Font, String, Size, Spacing, Depth, Radius, Inverted, Justification, Angle). Creates a text object with the bottom (or top) of the character cells aligned with all or part of a circle. This macro should be used inside an object{...} block.
Parameters:

Font = A string specifying the font to use.
String = The text string the object is generated from.
Size = A scaling value.
Spacing = The amount of space to add between the characters.
Depth = The thickness of the text object.
Radius = The radius of the circle the letters are aligned to.
Inverted = Controls what part of the text faces "outside". If this parameter is nonzero, the tops of the letters will point toward the center of the circle. Otherwise, the bottoms of the letters will do so.
Justification = Align_Left, Align_Right, or Align_Center.
Angle = The point on the circle from which rendering will begin. The +x direction is 0 and the +y direction is 90 (i.e. the angle increases anti-clockwise).

Wedge(Angle). This macro creates an infinite wedge shape, an intersection of two planes. It is mainly useful in CSG, for example to obtain a specific arc of a torus. The edge of the wedge is positioned along the y axis, and one side is fixed to the zy plane, the other side rotates clockwise around the y axis.
Parameters:

Angle = The angle, in degrees, between the sides of the wedge shape.

Spheroid(Center, Radius). This macro creates an unevenly scaled sphere. Radius is a vector where each component is the radius along that axis.
Parameters:

Center = Center of the spheroid.
Radius = A vector specifying the radii of the spheroid.

Supertorus(MajorRadius, MinorRadius, MajorControl, MinorControl, Accuracy, MaxGradient). This macro creates an isosurface of the torus equivalent of a superellipsoid. If you specify a MaxGradient of less than 1, evaluate will be used. You will have to adjust MaxGradient to fit the parameters you choose, a squarer supertorus will have a higher gradient. You may want to use the function alone in your own isosurface.
Parameters:

MajorRadius, MinorRadius = Base radii for the torus.
MajorControl, MinorControl = Controls for the roundness of the supertorus. Use numbers in the range [0, 1].
Accuracy = The accuracy parameter.
MaxGradient = The max_gradient parameter.

Supercone(EndA, A, B, EndB, C, D). This macro creates an object similar to a cone, but where the end points are ellipses. The actual object is an intersection of a quartic with a cylinder.
Parameters:

EndA = Center of end A.
A, B = Controls for the radii of end A.
EndB = Center of end B.
C, D = Controls for the radii of end B.

Connect_Spheres(PtA, RadiusA, PtB, RadiusB). This macro creates a cone that will smoothly join two spheres. It creates only the cone object, however, you will have to supply the spheres yourself or use the Round_Cone2() macro instead.
Parameters:

PtA = Center of sphere A.
RadiusA = Radius of sphere A.
PtB = Center of sphere B.
RadiusB = Radius of sphere B.

Wire_Box_Union(PtA, PtB, Radius), Wire_Box_Merge(PtA, PtB, Radius), Wire_Box(PtA, PtB, Radius, UseMerge). Creates a wire-frame box from cylinders and spheres. The resulting object will fit entirely within a box object with the same corner points.
Parameters:

PtA = Lower-left-front corner of box.
PtB = Upper-right-back corner of box.
Radius = The radius of the cylinders and spheres composing the object.
UseMerge = Whether or not to use a merge.

Round_Box_Union(PtA, PtB, EdgeRadius), Round_Box_Merge(PtA, PtB, EdgeRadius), Round_Box(PtA, PtB, EdgeRadius, UseMerge). Creates a box with rounded edges from boxes, cylinders and spheres. The resulting object will fit entirely within a box object with the same corner points. The result is slightly different from a superellipsoid, which has no truely flat areas.
Parameters:

PtA = Lower-left-front corner of box.
PtB = Upper-right-back corner of box.
EdgeRadius = The radius of the edges of the box.
UseMerge = Whether or not to use a merge.

Round_Cylinder_Union(PtA, PtB, Radius, EdgeRadius), Round_Cylinder_Merge(PtA, PtB, Radius, EdgeRadius), Round_Cylinder(PtA, PtB, Radius, EdgeRadius, UseMerge). Creates a cylinder with rounded edges from cylinders and tori. The resulting object will fit entirely within a cylinder object with the same end points and radius. The result is slightly different from a superellipsoid, which has no truely flat areas.
Parameters:

PtA, PtB = The end points of the cylinder.
Radius = The radius of the cylinder.
EdgeRadius = The radius of the edges of the cylinder.
UseMerge = Whether or not to use a merge.

Round_Cone_Union(PtA, RadiusA, PtB, RadiusB, EdgeRadius), Round_Cone_Merge(PtA, RadiusA, PtB, RadiusB, EdgeRadius), Round_Cone(PtA, RadiusA, PtB, RadiusB, EdgeRadius, UseMerge) Creates a cone with rounded edges from cones and tori. The resulting object will fit entirely within a cone object with the same end points and radii.
Parameters:

PtA, PtB = The end points of the cone.
RadiusA, RadiusB = The radii of the cone.
EdgeRadius = The radius of the edges of the cone.
UseMerge = Whether or not to use a merge.

Round_Cone2_Union(PtA, RadiusA, PtB, RadiusB), Round_Cone2_Merge(PtA, RadiusA, PtB, RadiusB), Round_Cone2(PtA, RadiusA, PtB, RadiusB, UseMerge). Creates a cone with rounded edges from a cone and two spheres. The resulting object will not fit entirely within a cone object with the same end points and radii because of the spherical caps. The end points are not used for the conical portion, but for the spheres, a suitable cone is then generated to smoothly join them.
Parameters:

PtA, PtB = The centers of the sphere caps.
RadiusA, RadiusB = The radii of the sphere caps.
UseMerge = Whether or not to use a merge.

Round_Cone3_Union(PtA, RadiusA, PtB, RadiusB), Round_Cone3_Merge(PtA, RadiusA, PtB, RadiusB) Round_Cone3(PtA, RadiusA, PtB, RadiusB, UseMerge). Like Round_Cone2(), this creates a cone with rounded edges from a cone and two spheres, and the resulting object will not fit entirely within a cone object with the same end points and radii because of the spherical caps. The difference is that this macro takes the end points of the conical portion and moves the spheres to be flush with the surface, instead of putting the spheres at the end points and generating a cone to join them.
Parameters:

PtA, PtB = The end points of the cone.
RadiusA, RadiusB = The radii of the cone.
UseMerge = Whether or not to use a merge.

Quad(A, B, C, D) and Smooth_Quad(A, NA, B, NB, C, NC, D, ND). These macros create "quads", 4-sided polygonal objects, using triangle pairs.
Parameters:

A, B, C, D = Vertices of the quad.
NA, NB, NC, ND = Vertex normals of the quad.

3.7.12.1.1 The HF Macros

There are several HF macros in shapes.inc, which generate meshes in various shapes. All the HF macros have these things in common:

The HF macros do not directly use an image for input, but evaluate a user-defined function. The macros deform the surface based on the function values.
The macros can either write to a file to be included later, or create an object directly. If you want to output to a file, simply specify a filename. If you want to create an object directly, specify "" as the file name (an empty string).
The function values used for the heights will be taken from the square that goes from <0,0,0> to <1,1,0> if UV height mapping is on. Otherwise the function values will be taken from the points where the surface is (before the deformation).
The texture you apply to the shape will be evaluated in the square that goes from <0,0,0> to <1,1,0> if UV texture mapping is on. Otherwise the texture is evaluated at the points where the surface is (after the deformation.

The usage of the different HF macros is described below.

HF_Square (Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, MnExt, MxExt). This macro generates a mesh in the form of a square height field, similar to the built-in height_field primitive. Also see the general description of the HF macros above.
Parameters:

Function = The function to use for deforming the height field.
UseUVheight = A boolean value telling the macro whether or not to use UV height mapping.
UseUVtexture = A boolean value telling the macro whether or not to use UV texture mapping.
Res = A 2D vector specifying the resolution of the generated mesh.
Smooth = A boolean value telling the macro whether or not to smooth the generated mesh.
FileName = The name of the output file.
MnExt = Lower-left-front corner of a box containing the height field.
MxExt = Upper-right-back corner of a box containing the height field.

HF_Sphere(Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, Center, Radius, Depth). This macro generates a mesh in the form of a spherical height field. When UV-mapping is used, the UV square will be wrapped around the sphere starting at +x and going anti-clockwise around the y axis. Also see the general description of the HF macros above. Parameters:

Function = The function to use for deforming the height field.
UseUVheight = A boolean value telling the macro whether or not to use UV height mapping.
UseUVtexture = A boolean value telling the macro whether or not to use UV texture mapping.
Res = A 2D vector specifying the resolution of the generated mesh.
Smooth = A boolean value telling the macro whether or not to smooth the generated mesh.
FileName = The name of the output file.
Center = The center of the height field before being displaced, the displacement can, and most likely will, make the object off-center.
Radius = The starting radius of the sphere, before being displaced.
Depth = The depth of the height field.

HF_Cylinder(Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, EndA, EndB, Radius,Depth). This macro generates a mesh in the form of an open-ended cylindrical height field. When UV-mapping is used, the UV square will be wrapped around the cylinder. Also see the general description of the HF macros above.
Parameters:

Function = The function to use for deforming the height field.
UseUVheight = A boolean value telling the macro whether or not to use UV height mapping.
UseUVtexture = A boolean value telling the macro whether or not to use UV texture mapping.
Res = A 2D vector specifying the resolution of the generated mesh.
Smooth = A boolean value telling the macro whether or not to smooth the generated mesh.
FileName = The name of the output file.
EndA, EndB = The end points of the cylinder.
Radius = The (pre-displacement) radius of the cylinder.
Depth = The depth of the height field.

HF_Torus (Function, UseUVheight, UseUVtexture, Res, Smooth, FileName, Major, Minor, Depth). This macro generates a mesh in the form of a torus-shaped height field. When UV-mapping is used, the UV square is wrapped around similar to spherical or cylindrical mapping. However the top and bottom edges of the map wrap over and under the torus where they meet each other on the inner rim. Also see the general description of the HF macros above.
Parameters:

Function = The function to use for deforming the height field.
UseUVheight = A boolean value telling the macro whether or not to use UV height mapping.
UseUVtexture = A boolean value telling the macro whether or not to use UV texture mapping.
Res = A 2D vector specifying the resolution of the generated mesh.
Smooth = A boolean value telling the macro whether or not to smooth the generated mesh.
FileName = The name of the output file.
Major = The major radius of the torus.
Minor = The minor radius of the torus.

3.7.12.2 shapes_old.inc

Ellipsoid, Sphere: Unit-radius sphere at the origin.
Cylinder_X, Cylinder_Y, Cylinder_Z: Infinite cylinders.
QCone_X, QCone_Y, QCone_Z: Infinite cones.
Cone_X, Cone_Y, Cone_Z: Closed capped cones: unit-radius at -1 and 0 radius at +1 along each axis.
Plane_YZ, Plane_XZ, Plane_XY: Infinite planes passing through the origin.
Paraboloid_X, Paraboloid_Y, Paraboloid_Z: y^2 + z^2 - x = 0
Hyperboloid, Hyperboloid_Y: y - x^2 + z^2 = 0
UnitBox, Cube: A cube 2 units on each side, centered on the origin.
Disk_X, Disk_Y, Disk_Z: "Capped" cylinders, with a radius of 1 unit and a length of 2 units, centered on the origin.

3.7.12.3 shapes2.inc

Tetrahedron: 4-sided regular polyhedron.
Octahedron: 8-sided regular polyhedron.
Dodecahedron: 12-sided regular polyhedron.
Icosahedron: 20-sided regular polyhedron.
Rhomboid: Three dimensional 4-sided diamond, basically a sheared box.
Hexagon: 6-sided regular polygonal solid, axis along x.
HalfCone_Y: Convenient finite cone primitive, pointing up in the Y axis.
Pyramid: 4-sided pyramid (union of triangles, can not be used in CSG).
Pyramid2: 4-sided pyramid (intersection of planes, can be used in CSG).
Square_X, Square_Y, Square_Z: Finite planes stretching 1 unit along each axis. In other words, 2X2 unit squares.

3.7.12.4 shapesq.inc

Bicorn: This curve looks like the top part of a paraboloid, bounded from below by another paraboloid. The basic equation is:; y^2 - (x^2 + z^2) y^2 - (x^2 + z^2 + 2 y - 1)^2 =
Crossed_Trough: This is a surface with four pieces that sweep up from the x-z plane.; The equation is: y = x^2 z^2
Cubic_Cylinder: A drop coming out of water? This is a curve formed by using the equation:; y = 1/2 x^2 (x + 1); as the radius of a cylinder having the x-axis as its central axis. The final form of the equation is:; y^2 + z^2 = 0.5 (x^3 + x^2)
Cubic_Saddle_1: A cubic saddle. The equation is: z = x^3 - y^3
Devils_Curve: Variant of a devil's curve in 3-space. This figure has a top and bottom part that are very similar to a hyperboloid of one sheet, however the central region is pinched in the middle leaving two teardrop shaped holes. The equation is:; x^4 + 2 x^2 z^2 - 0.36 x^2 - y^4 + 0.25 y^2 + z^4 = 0
Folium: This is a folium rotated about the x-axis. The formula is:; 2 x^2 - 3 x y^2 - 3 x z^2 + y^2 + z^2 = 0
Glob_5: Glob - sort of like basic teardrop shape. The equation is:; y^2 + z^2 = 0.5 x^5 + 0.5 x^4
Twin_Glob: Variant of a lemniscate - the two lobes are much more teardrop-like.
Helix, Helix_1: Approximation to the helix z = arctan(y/x). The helix can be approximated with an algebraic equation (kept to the range of a quartic) with the following steps:; tan(z) = y/x => sin(z)/cos(z) = y/x =>
(1) x sin(z) - y cos(z) = 0 Using the taylor expansions for sin, cos about z = 0,
sin(z) = z - z^3/3! + z^5/5! - ...
cos(z) = 1 - z^2/2! + z^6/6! - ...
Throwing out the high order terms, the expression (1) can be written as:
x (z - z^3/6) - y (1 + z^2/2) = 0, or

(2) -1/6 x z^3 + x z + 1/2 y z^2 - y = 0
This helix (2) turns 90 degrees in the range 0 <= z <= sqrt(2)/2. By using scale <2 2 2>, the helix defined below turns 90 degrees in the range 0 <= z <= sqrt(2) = 1.4042.
Hyperbolic_Torus: Hyperbolic Torus having major radius sqrt(40), minor radius sqrt(12). This figure is generated by sweeping a circle along the arms of a hyperbola. The equation is:; x^4 + 2 x^2 y^2 - 2 x^2 z^2 - 104 x^2 + y^4 - 2 y^2 z^2 + 56 y^2 + z^4 + 104 z^2 + 784 = 0
Lemniscate: Lemniscate of Gerono. This figure looks like two teardrops with their pointed ends connected. It is formed by rotating the Lemniscate of Gerono about the x-axis. The formula is:; x^4 - x^2 + y^2 + z^2 = 0
Quartic_Loop_1: This is a figure with a bumpy sheet on one side and something that looks like a paraboloid (but with an internal bubble). The formula is:; (x^2 + y^2 + a c x)^2 - (x^2 + y^2)(c - a x)^2; -99*x^4+40*x^3-98*x^2*y^2-98*x^2*z^2+99*x^2+40*x*y^2; +40*x*z^2+y^4+2*y^2*z^2-y^2+z^4-z^2
Monkey_Saddle: This surface has three parts that sweep up and three down. This gives a saddle that has a place for two legs and a tail... The equation is:; z = c (x^3 - 3 x y^2); The value c gives a vertical scale to the surface - the smaller the value of c, the flatter the surface will be (near the origin).
Parabolic_Torus_40_12: Parabolic Torus having major radius sqrt(40), minor radius sqrt(12). This figure is generated by sweeping a circle along the arms of a parabola. The equation is:; x^4 + 2 x^2 y^2 - 2 x^2 z - 104 x^2 + y^4 - 2 y^2 z + 56 y^2 + z^2 + 104 z + 784 = 0
Piriform: This figure looks like a hersheys kiss. It is formed by sweeping a Piriform about the x-axis. A basic form of the equation is:; (x^4 - x^3) + y^2 + z^2 = 0.
Quartic_Paraboloid: Quartic parabola - a 4th degree polynomial (has two bumps at the bottom) that has been swept around the z axis. The equation is:; 0.1 x^4 - x^2 - y^2 - z^2 + 0.9 = 0
Quartic_Cylinder: Quartic Cylinder - a Space Needle?
Steiner_Surface: Steiners quartic surface
Torus_40_12: Torus having major radius sqrt(40), minor radius sqrt(12).
Witch_Hat: Witch of Agnesi.
Sinsurf: Very rough approximation to the sin-wave surface z = sin(2 pi x y).; In order to get an approximation good to 7 decimals at a distance of 1 from the origin would require a polynomial of degree around 60, which would require around 200,000 coefficients. For best results, scale by something like <1 1 0.2>.