TrainFaces 

Version 1.0.0 

TrainFaces Demo Image ThumbnailThe TrainFaces include file was originally designed to create Thomas the Tank Engine style faces, hence its name.  However, it should be flexible enough at this point to be used for other purposes as well.  It can generate face objects, allowing the position, size, shape, and texture, of the eyes, nose, mouth, eyebrows, cheeks, and chin to be customized.  Additionally there is the capability of saving the face to a mesh for fast rendering.

Please feel free to contact me with any comments, questions, or issues, at povray at bherring dot cotse dot net.

  Basic Usage

Simply include the “trainfaces.inc” file in your scene: 

#include “trainfaces.inc” 

Then, after setting any desired options, call the TF_Face macro, which will return an object: 

#declare Face = TF_Face(); 

or 

object { 

  TF_Face()

  // transformations go here

 

  Options

There are a number of options that control the shape of the face, placement of facial features, texturing, and object generation.  All options are set by declaring variables before calling the TF_Face macro.  For example:

#declare TF_Some_Option = 42; 

  Default Options

All options have default values, and they are automatically set to these values when the trainfaces.inc file is first included.  The default values for all variables are listed below with their descriptions.

TF_Set_Default

The macro TF_Set_Default will reset all variable options to their default values.  It is useful to call before setting any options to ensure consistency.  It is used simply:

TF_Set_Default()

  General Structure

 

Name 

Type 

Default 

Use 

 

TF_Shape 

Integer 

Defines the overall shape of the face. Currently there are two shapes defined. 

  1. Rounded Circular 

  2. Rounded square 

Example

TF_Show_Eyes 

Boolean 

On 

Enables/disables creation of eyes and eye sockets.  If disabled, eye related options have no effect.

Example

TF_Show_Nose 

Boolean 

On 

Enables/disables creation of a nose.  If disabled, nose related options have no effect.

TF_Show_Mouth 

Boolean 

On 

Enables/disables creation of a mouth.  If disabled, mouth related options have no effect.

TF_Show_Cheeks 

Boolean 

On 

Enables/disables creation of cheeks.  If disabled, cheek related options have no effect.  An exception to this is that TF_Cheek_Rosy still functions, and TF_Cheek_Scale will affect the size of the coloring.

TF_Show_Brows 

Boolean 

On 

Enables/disables creation of eyebrows.  If disabled, brow related options have no effect.  Additionally TF_Brow_Style must be a value other than zero if eyebrows are to be visible.

TF_Show_Chin 

Boolean 

On 

Enables/disables creation of a chin.  If disabled, chin related options have no effect.

TF_Face_T 

Texture 

TF_Default_Face_T 

The texture to be applied to the face. 

Example

TF_Face_I 

Interior 

TF_Default_Face_I 

The interior to be applied to the face. 

 

  Eyes

Name 

Type 

Default 

Use 

 

TF_Eye_Style 

Integer 

Defines the style of the eye/pupil.  Currently the following styles are defined:

  1. Elliptical eye and pupils 

  2. Elliptical eye and pupils, with stylized pupil highlight 

Example

TF_Eye_Scale 

2D vector 

<1, 1> 

Defines scaling of the eyes/eye sockets in the x and y directions.  The pupils are not affected by this option, see TF_Pupil_Scale.

Example

TF_Pupil_Scale 

2D vector 

<1, 1> 

Defines scaling of the pupils only, in the x and y directions. 

Example

TF_Eye_Place 

2D vector 

<0, 0> 

Defines an adjustment to the placement of the eyes in the x and y directions. A negative x value will move both eyes closer together, while a positive x value will move them further apart. 

Example

TF_Look_At 

3D vector 

-z 

The vector defines the direction both eyes will point in.  The center of each eye is assumed to be at the origin for the purposes of interpreting this value. Reasonable values should be consistent with the fact that a face is initially created faced in the z direction.

Example

TF_Eye_T 

Texture 

TF_Default_Eye_T 

Defines the texture to be applied to the eye (except for the pupil.) 

Example

TF_Pupil_T 

Texture 

TF_Default_Pupil_T 

Defines the texture to be applied to the pupils of each eye. 

TF_Eye_I 

Interior 

TF_Default_Eye_I 

Defines the interior that will be applied to each eye object. 

 

  Nose

Name 

Type 

Default 

Use 

 

TF_Nose_Place 

Float 

Adjusts the placement of the nose.  Negative values place it lower on the face, while positive values place it higher.

Example

TF_Nose_Tilt 

Float 

Defines the angle at which the nose protrudes from the face.  Negative values tilt upwards, positive downwards.

Example

TF_Nose_Length 

Float 

0.3 

Sets the approximate length of the nose from base to tip. 

Example

TF_Nose_Size 

2D vector 

<0.15, 0.1> 

The nose is roughly cone shaped.  The u and v elements of this vector specify the radius of the cone at the base and tip, respectively.  Generally, u should be less than or equal to v.

Example

  Mouth

 

Name 

Type 

Default 

Use 

 

TF_Mouth_Shape 

3D vector 

<0.6, 0.05, 0.1> 

The x component defines the horizontal width of the mouth, from left to right corner.  The y and z values define the vertical offset from the baseline of the mouth of the top and bottom lips.  The smaller of y and z is assumed to be the top lip, with the larger being the bottom.  If y and z are both positive, the mouth is smiling; both negative, frowning; one positive and one negative gives a rounded mouth.

Example

TF_Mouth_Scale 

2D vector 

<1, 1> 

Defines scaling of the mouth in the x and y directions. 

Example

TF_Mouth_Place 

2D vector 

<0, 0> 

Offsets the location of the mouth in the x and y directions. 

Example

TF_Mouth_M 

Material 

TF_Default_Mouth_M 

Defines the material applied to the inside of the mouth. 

Example

  Eyebrows

Name 

Type 

Default 

Use 

 

TF_Brow_Style 

Integer 

Sets what kind of eyebrows are created.  Currently the following styles are defined:

  1. No eyebrows 

  2. Angular, "caret shaped" 

  3. Curved and tapered 

  4. Horizontal bars 

  5. Arcs 

Example

TF_Brow_Scale 

2D vector 

<1, 1> 

Sets the scaling of each eyebrow in the x and y directions. 

Example

TF_Brow_Place 

2D vector 

<0, 0> 

Offsets the eyebrows location in the x and y directions.  Negative x values will move the brows closer together, positive values move them farther apart.

Example

TF_Brow_Tilt 

Float 

Rotates each brow around the z axis by this angle. 

Example

TF_Brow_T 

Texture 

TF_Default_Brow_T 

Sets the texture to be applied to the eyebrows. 

Example

 

  Cheeks

Name 

Type 

Default 

Use 

 

TF_Cheek_Scale 

3D vector 

<1, 1, 1> 

Sets the scaling of the cheeks and the areas of color if TF_Cheek_Rosy is enabled. 

Example

TF_Cheek_Place 

2D vector 

<0, 0> 

Offset to be applied to the cheek location in the x and y directions.  Negative x values will move the cheeks closer together, positive values further apart.

Example

TF_Cheek_Rosy 

Boolean 

Off 

Enables/disables round patches of color on the cheeks.  Note this option still works if cheeks are disabled.

Example

TF_Rosy_T 

Texture 

TF_Default_Rosy_T 

Sets the texture to use for the coloration when TF_Cheek_Rosy is enabled. 

  Chin

 

Name 

Type 

Default 

Use 

 

TF_Chin_Scale 

3D vector 

<1, 1, 1> 

Sets the scaling of the chin in the x, y, and z directions. 

Example

TF_Chin_Place 

2D vector 

<0, 0> 

Adjusts the location of the chin in the x and y directions.  By default the chin is centered horizontally on the face.  A positive x offset creates a cleft, widening the chin.

Example

  Isosurface Options

Name 

Type 

Default 

Use 

TF_File 

String 

Empty string 

By default the shape of a face is created using an isosurface.  If TF_File is given a non-empty value, it will be considered a file name containing a mesh object defining the face.  If the file name given does not exist, a mesh approximation of the face isosurface will be generated and stored in the file.  This feature is only available if an Isosurface Approximation include file is available, not included in this package.  This will be discussed further below.  If the file does exists, it will be included as the face instead of generating the isosurface. The approximation macro is not necessary to load an existing mesh file.

 

If a mesh file is loaded for the face, the shape is fixed and options that change the shape will not function.  The following options can still be changed and will work correctly:  TF_Show_Brows, TF_Eye_Style, TF_Pupil_Scale, TF_Look_At, TF_Eye_T, TF_Pupil_T, TF_Eye_I, TF_Mouth_M, TF_Brow_Style, TF_Brow_Scale, TF_Brow_Place, TF_Brow_Tilt, TF_Brow_T, TF_Cheek_Rosy, TF_Cheek_Scale (rosy only), TF_Cheek_Place (rosy only), TF_Rosy_T, TF_Face_T, TF_Face_I.

 

The following options should be set to the same values as when the mesh was created: TF_Show_Eyes, TF_Eye_Scale, TF_Eye_Place. 

TF_Name 

String 

Empty string 

When creating and/or loading a mesh file, if TF_Name is non-empty its value will be interpreted as a variable containing the mesh object.  If the variable is undefined the mesh will be created and/or loaded and assigned to the variable.  If the variable is defined it will be used as the mesh object and any creation/loading will be skipped. This option should be used any time the same mesh file is used more than once in a scene, as it can dramatically reduce both parse time and memory usage.

TF_Iso_Inc 

String 

"isosurface_KL_JF_TOK_JF.inc" 

Defines the include file name for the Isosurface Approximation include file.  The latest version as of this writing was written by Kevin Loney, Jaap Frank, and Tor Olav Kristensen, and is available here. Some information about its use is available here.

TF_Iso_Min 

3D vector 

Undefined (automatic) 

Defines the minimum corner of the container box for the face isosurface.  If undefined it will be calculated automatically.  Generally this should not be changed, but if the face appears clipped it might be useful.

TF_Iso_Max 

3D vector 

<1.1, 1.1, 0.25> 

Defines the maximum corner of the isosurface container.  Generally it doesn't need to be changed, but it clipping is seen then it might be useful.

TF_Iso_Segs 

3D vector 

<100, 100, 100> 

Defines the resolution of the mesh approximation.  The higher the values the more accurate the result, but parse time will increase.  If holes appear in the mesh, try increasing this value.

TF_Iso_Depth 

Integer 

If greater than zero, the approximation will perform the given number of subdivision steps on the mesh.  This will not close holes, but it will make the mesh smoother. The fairly high setting required for TF_Iso_Segs usually makes this unnecessary.

CC-GNU LGPL

This software is licensed under the CC-GNU LGPL