Reference:Shapes.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.
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 physical 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.
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.