Each time you use the POV-Person macro in your POVRay scene file you use a selection of the POV-Person library files to build a character. The character is defined by optionally setting control variables and by specifying control files on the POV-Person macro call. The POV-Person macro uses this information to build a character that you can use inline within your POVRay scene, or that you can assign to a named object that you can use later in your scene.

Character

A series of standard character files are provided with POV-Person to illustrate the use of the control parameters and the supplied model files. You can set up your own control files to adjust the supplied characters and you can add model files to generate completely different figures. This section describes the standard character files and the corresponding control parameters.

The models supplied with POV-Person V2 are all based upon a single anatomical definition. This definition is known as pphuman001 and describes how body parts are assembled into a human-like form. It defines the names of body parts and the relationship between their joints. The various models that use this anatomical definition describe the individual body parts and the relative scaling to use to assemble a particular character.

The following models are supplied with POV-Person:
ModelDescriptionCharacters
f1Female model with rigid face mesh.The ppann.inc character uses this model.
f2Female model. Mostly rigid face mesh with dynamic eyelids and lips.The ppbabs.inc character uses this model.
m1Male model with rigid face mesh.The ppalf.inc character uses this model.
m2Male model with rigid face mesh.The ppbill.inc character uses this model.
r1Randomly selected and scaled body parts. Randomly selected face mesh.The pprandy.inc character uses this model.
s1Stickman model using cylinders and spheres.The pprod.inc character uses this model.

To create a new character file it is recommended that you copy an existing file and tailor it. Remember not to use the 'pp' prefix for your own character file so as to avoid conflicts with future versions of POV-Person.

The first part of a character file defines the model prefix (ppf1), character template (pphuman001) and gender (female)to use.

#declare ppModelPrefix = "ppf1";
#declare ppGender = "female";
#declare ppCharacterTemplate = "pphuman001";
It is possible to use an essentially female model such as ppf1 with a gender of 'male' and to specify things such as a beard and hairstyle to give it a more masculin appearance.

The remainder of a character file specifies attributes of the character, such as:
DeclarationDescriptionPossible values
#declare ppSkinDarkness=1.2; The darkness of the skin colour0.7 to 8 1 is default, 2 is more dark
#declare ppSkinRedness=1.1; A factor to control the amount of redness in the skin colour0.9 to 2 1 is not very red, 1.5 is redder
#declare ppSkinNoiseGenerator=3; Which of POV-Rays noise generators to use 1-3. See noise_generator in the POV-Ray Help
#declare ppEyeColour = 3; Base colour for eye1=Blue, 2=Brown, 3=Green
#declare ppEyeBrightness = 1.5; A factor to control the brightness of the eye colour0.5 = Dark, 1.5 = Bright
#declare ppEyePupil = 1; A factor to control the dilation of the pupil1.35 = dilated (big black bit), 0.35 = constricted (small black bit)
#declare ppEyePosition = <13.2, 80.6, -3.5>;Position of the eyes relative to the face meshThis needs to match the model as defined by the model prefix
#declare ppChestSize = 1.2; A factor to control the chest muscle size0.5 for men, 0.8 to 1.2 for women
#declare ppBreastSize = 1; A factor to control the breast size0.5 for men, 0.8 to 1.2 for women

For male characters it is customary to include such things as hair colour in the character file, whereas such things are conventionaly recorded in the style file for female characters.

Style

A style file is used to record such things as hairstyles, makeup, eye lash length etc. A series of style files are provided with POV-Person V2 to illustrate the capabilities of the library. You can set up your own style files. It is recommended that you copy an existing file and tailor it. Remember not to use the 'pp' prefix for your own style file so as to avoid conflicts with future versions of POV-Person.

Expression

With POV-Person V2 you have a limited degree of control over the expression on the face of a figure. All of the characters permit the eyes to be moved. The 'f2' character also permits the eyelids to be opened and closed. It also permits a degree of control over the profile of the lips, but this is not currently achieved through the Expressions file.

There are two main ways of controlling the direction of the eyes. You can explicitly specify rotations or you can specify a point for the figure to look at.

To specify the eye rotations use the ppLeftEyeRotation and the ppRightEyeRotation control variables. For example:

#declare ppLeftEyeRotation = <0,5,15>;
#declare ppRightEyeRotation = <0,5,15>;

tells POV-Person to rotate each eye 5 degrees to the right and 15 degrees downwards. For an explanation of the sequence of rotations, see the joint definitions in the table in the section below on 'Poses'.

To specify a point in space for the figure to look at, use the ppLookAt control variable. Note however that this position is relative to the position in which the figure is defined and does not, by default, take account of any transformations you apply to the figure after it has been defined. In order to alleviate the difficulty of calculating the coordinates of the point to look at, when you plan to subsequently transform the figure, POV-Person allows you to declare the ppTransformFigure transform and, if declared, will take this into account when calculating the rotations of the eyes. POV-Person only uses this transform for the eye rotations and not for positioning the figure. You are left to apply the transform to the figure. For example:

#declare ppLookAt = <0, 2,-5>;
#declare ppTransformFigure = transform {rotate 180*y translate <-0.05,0,0.4>};
#declare Figure = object {
   ppFigure("ppbabs.inc","ppstyle4.inc","pplookdown.inc","ppstanding.inc","ppoutfit1.inc")
   transform ppTransformFigure
}

declares a point in space for the figure to look at. The use of ppTransformFigure tells POV-Person about the transformation that is going to be applied to the figure after it has been defined. So, if in this example you also use the point <0,2,-5> for the camera location, the figure will be looking straight at the camera, irrespective of the tranformations you put into ppTransformFigure.

You can use the ppLookAt control variable in conjunction with the ppLeftEyeRotation and the ppRightEyeRotation control variables. In this case the point specified using ppLookAt is evaluated first, then the rotations specified are applied to each eye. For example, you could use the ppLookAt control variable to identify the camera position and the following eye rotations to force the eyes to look slightly down from that camera position.

#declare ppLeftEyeRotation = <0,0,5>;
#declare ppRightEyeRotation = <0,0,5>;

The 'f2' model allows you to open and close the eyelids. The following control variables set the upper eye lids to be raised by 10 degrees and the lower eyelids to be lowered by 15 degrees.

#declare ppLeftUpperEyelidAngle = 10;
#declare ppLeftLowerEyelidAngle = -15;
#declare ppRightUpperEyelidAngle = 10;
#declare ppRightLowerEyelidAngle = -15;

Pose

When posing a figure it is important to understand the start position of the figure, its joints and their orientations.

The default pose for the pphuman001 model is - standing upright at the origin facing out along the positive z axis. The arms are down by the side of the figure with the palms facing in towards the body. To pose the figure it can help to imagine yourself standing behind the figure and mapping your body positions onto it.

To pose a figure you rotate the various joints using the ppRotateJoint macro, which takes a joint reference and 3 rotations as parameters. Important. The joint rotations are relative to the body parts on either side of the joint and not to any absolute position. There are some general rules that it is helpful to bear in mind when defining and posing figures:

To create your own pose it is recommended that you copy a pose file that is close to the pose you need, then adjust your copy. Remember not to use the 'pp' prefix for your new file as this is reserved for future versions of POV-Person. For example, if you wish to create a hopping pose that is similar to the ppwalking2.inc pose file and your name is John Smith, you might copy ppwalking2.inc to a file called 'jshopping.inc', then add joint rotations to create your pose. The following table lists the variables defined by the pphuman001 model to hold the joint references. It also describes the joint rotations (as controlled by the ppRotateJoint macro). These describe the result when you specify a positive angle of rotation. To get the reverse effect, specify a negative rotation.
Joint referenceAxesTwistPrincipal RotationRotation 3Notes
ppUpperNeckJointRef y, x, zTurn head to right Bow head forward Tilt head to left
ppLowerNeckJointRef y, x, zTurn head to right Bow head forward Tilt head to left
ppChestAbdomenJointRef y, x, zTurn chest to right Tilt chest forward Tilt chest to left
ppAbdomenHipJointRef y, x, zTurn abdomen to right Bow abdomen forward Tilt abdomen to left
ppLeftShoulderBladeJointRef y,-x,-zTurn shoulder blade clockwise Tilt shoulder blade backRotate shoulder blade in towards neck(Consider revising)
ppLeftShoulderJointRef y,-x,-zTwist arm clockwise Swing arm forward Lift arm
ppLeftElbowJointRef y,-x,-zTurn lower arm clockwise Bend lower arm upward Not normally used
ppLeftWristJointRef y, z,-xTwist hand clockwise Bend wrist forward Swivel towards thumb
ppLeftThumbBaseJointRef y, z,-xTwist thumb clockwise Open thumb perpendicularOpen thumb lateral
ppLeftThumbMiddleJointRef y, z,-xNot normally used Clench thumb Not normally used
ppLeftThumbTipJointRef y, z,-xNot normally used Clench tip of thumb Not normally used
ppLeftFirstFingerBaseJointRef y, z,-xTwist clockwise (used sparingly)Bend forward Swivel towards thumb
ppLeftFirstFingerMiddleJointRef y, z,-xNot normally used Clench finger Not normally used
ppLeftFirstFingerTipJointRef y, z,-xNot normally used Clench finger tip Not normally used
ppLeftMiddleFingerBaseJointRef y, z,-xTwist clockwise (used sparingly)Bend forward Swivel towards thumb
ppLeftMiddleFingerMiddleJointRef y, z,-xNot normally used Clench finger Not normally used
ppLeftMiddleFingerTipJointRef y, z,-xNot normally used Clench finger tip Not normally used
ppLeftThirdFingerBaseJointRef y, z,-xTwist clockwise (used sparingly)Bend forward Swivel towards thumb
ppLeftThirdFingerMiddleJointRef y, z,-xNot normally used Clench finger Not normally used
ppLeftThirdFingerTipJointRef y, z,-xNot normally used Clench finger tip Not normally used
ppLeftLittleFingerBaseJointRef y, z,-xTwist clockwise (used sparingly)Bend forward Swivel towards thumb
ppLeftLittleFingerMiddleJointRef y, z,-xNot normally used Clench finger Not normally used
ppLeftLittleFingerTipJointRef y, z,-xNot normally used Clench finger tip Not normally used
ppLeftThumbNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftFirstFingerNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftMiddleFingerNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftThirdFingerNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftLittleFingerNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftHipJointRef y,-x, zTwist leg clockwise Lift leg Turn leg in towards right leg
ppLeftKneeJointRef y, x, zTwist calf clockwise Bend knee Not normally used
ppLeftAnkleJointRef y, x, zTwist foot clockwise Point foot downwards Tilt foot onto outer edge
ppLeftBigToeBaseJointRef z, x, yTwist toe anticlockwise Bend toe downwards Turn away from other toes
ppLeftBigToeTipJointRef z, x, yNot normally used Bend tip downwards Not normally used
ppLeftFirstToeBaseJointRef z, x, yTwist toe anticlockwise Bend toe downwards Turn towards big toe
ppLeftFirstToeMiddleJointRef z, x, yNot normally used Clench toe Not normally used
ppLeftFirstToeTipJointRef z, x, yNot normally used Bend tip downwards Not normally used
ppLeftMiddleToeBaseJointRef z, x, yTwist toe anticlockwise Bend toe downwards Turn towards big toe
ppLeftMiddleToeMiddleJointRef z, x, yNot normally used Clench toe Not normally used
ppLeftMiddleToeTipJointRef z, x, yNot normally used Bend tip downwards Not normally used
ppLeftThirdToeBaseJointRef z, x, yTwist toe anticlockwise Bend toe downwards Turn towards big toe
ppLeftThirdToeMiddleJointRef z, x, yNot normally used Clench toe Not normally used
ppLeftThirdToeTipJointRef z, x, yNot normally used Bend tip downwards Not normally used
ppLeftLittleToeBaseJointRef z, x, yTwist toe anticlockwise Bend toe downwards Turn towards big toe
ppLeftLittleToeMiddleJointRef z, x, yNot normally used Clench toe Not normally used
ppLeftLittleToeTipJointRef z, x, yNot normally used Bend tip downwards Not normally used
ppLeftBigToeNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftFirstToeNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftMiddleToeNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftThirdToeNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftLittleToeNailJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftLipsJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftEyeJointRef z, y, xNot normally used Look to right Look down Optional. Left eye rotations are usually set in the Expression file using the ppLeftEyeRotation control variable or the ppLookAt control variable.
ppLeftEarJointRef x, y, zNot normally used Not normally used Not normally used Optional
ppLeftUpperLashJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftLowerLashJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppLeftEyeBrowJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppUpperTeethJointRef y, x, zNot normally used Rotate downwards Not normally used Optional
ppLowerTeethJointRef y, x, zNot normally used Rotate downwards Not normally used Optional (Consider revising)
ppHairJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppBeardJointRef y, x, zNot normally used Not normally used Not normally used Optional
ppRightShoulderBladeJointRef -y,-x, zTurn shoulder blade anticlockwise Tilt shoulder blade backRotate shoulder blade in towards neck(Consider revising)
ppRightShoulderJointRef -y,-x, zTwist arm anticlockwise Swing arm forward Lift arm
ppRightElbowJointRef -y,-x, zTurn lower arm anticlockwise Bend lower arm upward Not normally used
ppRightWristJointRef -y,-z,-xTwist hand anticlockwise Bend wrist forward Swivel towards thumb
ppRightThumbBaseJointRef -y,-z,-xTwist thumb anticlockwise Open thumb perpendicularOpen thumb lateral
ppRightThumbMiddleJointRef -y,-z,-xNot normally used Clench thumb Not normally used
ppRightThumbTipJointRef -y,-z,-xNot normally used Clench tip of thumb Not normally used
ppRightFirstFingerBaseJointRef -y,-z,-xTwist anticlockwise (used sparingly)Bend forward Swivel towards thumb
ppRightFirstFingerMiddleJointRef -y,-z,-xNot normally used Clench finger Not normally used
ppRightFirstFingerTipJointRef -y,-z,-xNot normally used Clench finger tip Not normally used
ppRightMiddleFingerBaseJointRef -y,-z,-xTwist anticlockwise (used sparingly)Bend forward Swivel towards thumb
ppRightMiddleFingerMiddleJointRef-y,-z,-xNot normally used Clench finger Not normally used
ppRightMiddleFingerTipJointRef -y,-z,-xNot normally used Clench finger tip Not normally used
ppRightThirdFingerBaseJointRef -y,-z,-xTwist anticlockwise (used sparingly)Bend forward Swivel towards thumb
ppRightThirdFingerMiddleJointRef -y,-z,-xNot normally used Clench finger Not normally used
ppRightThirdFingerTipJointRef -y,-z,-xNot normally used Clench finger tip Not normally used
ppRightLittleFingerBaseJointRef -y,-z,-xTwist anticlockwise (used sparingly)Bend forward Swivel towards thumb
ppRightLittleFingerMiddleJointRef-y,-z,-xNot normally used Clench finger Not normally used
ppRightLittleFingerTipJointRef -y,-z,-xNot normally used Clench finger tip Not normally used
ppRightThumbNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightFirstFingerNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightMiddleFingerNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightThirdFingerNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightLittleFingerNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightHipJointRef -y,-x,-zTwist leg anticlockwise Lift leg Turn leg in towards right leg
ppRightKneeJointRef -y, x,-zTwist calf anticlockwise Bend knee Not normally used
ppRightAnkleJointRef -y, x,-zTwist foot anticlockwise Point foot downwards Tilt foot onto outer edge
ppRightBigToeBaseJointRef -z, x,-yTwist toe clockwise Bend toe downwards Turn away from other toes
ppRightBigToeTipJointRef -z, x,-yNot normally used Bend tip downwards Not normally used
ppRightFirstToeBaseJointRef -z, x,-yTwist toe clockwise Bend toe downwards Turn towards big toe
ppRightFirstToeMiddleJointRef -z, x,-yNot normally used Clench toe Not normally used
ppRightFirstToeTipJointRef -z, x,-yNot normally used Bend tip downwards Not normally used
ppRightMiddleToeBaseJointRef -z, x,-yTwist toe clockwise Bend toe downwards Turn towards big toe
ppRightMiddleToeMiddleJointRef -z, x,-yNot normally used Clench toe Not normally used
ppRightMiddleToeTipJointRef -z, x,-yNot normally used Bend tip downwards Not normally used
ppRightThirdToeBaseJointRef -z, x,-yTwist toe clockwise Bend toe downwards Turn towards big toe
ppRightThirdToeMiddleJointRef -z, x,-yNot normally used Clench toe Not normally used
ppRightThirdToeTipJointRef -z, x,-yNot normally used Bend tip downwards Not normally used
ppRightLittleToeBaseJointRef -z, x,-yTwist toe clockwise Bend toe downwards Turn towards big toe
ppRightLittleToeMiddleJointRef -z, x,-yNot normally used Clench toe Not normally used
ppRightLittleToeTipJointRef -z, x,-yNot normally used Bend tip downwards Not normally used
ppRightBigToeNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightFirstToeNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightMiddleToeNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightThirdToeNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightLittleToeNailJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightLipsJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightEyeJointRef z, y, xNot normally used Look to right Look down Optional. Right eye rotations are usually set in the Expression file using the ppRightEyeRotation control variable or the ppLookAt control variable.
ppRightEarJointRef x,-y,-zNot normally used Not normally used Not normally used Optional
ppRightUpperLashJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightLowerLashJointRef -y, x,-zNot normally used Not normally used Not normally used Optional
ppRightEyeBrowJointRef -y, x,-zNot normally used Not normally used Not normally used Optional

Costume

Costumes are added to a figure by specifying the name of that control file as the final parameter on the call to the ppFigure macro. This control file contains settings to control the generation of clothing and other costume elements. These settings are used to run macros that take the model and draw accessories around the appropriate body parts.

Several costume files are provided with POV-Person
ppoutfit1.incadds a shirt, trousers and a high heeled boot to each leg of the figure
ppoutfit2.incadds a shirt and shorts to the figure
pprandomoutfit.incadds a shirt and either shorts or trousers to the figure
It is recommended that you do not change these costume files. You can add your own costume files by copying one of the existing files and adjusting the parameters as required to generate clothing that meets your needs. Remember to avoid using the 'pp' prefix for the file name to help maintain compatibility with future versions of POV-Person.

The costume file contains two main groups. These can be specified in either order. The first is an array that contains a list of files containing the costume elements that you wish to add to your figure. The second is a series of control variables that control the various costume elements.

The following sample illustrates the declaration of the ppCostumeItems array

#declare ppCostumeItems = array [3] {
"ppboot1.inc",
"ppshorts1.inc",
"ppshirts1.inc"
}
This declares 3 costume files. When POV-Person has calculated the positions and orientations of the body parts it will include these files and run the macros contained in them to generate costume elements around those body parts.
Copyright Chris Bartlett 2005.
You are authorised to re-use this document in original or modified form for both commercial or non-commercial purposes, with or without credit being given to the author, provided that such re-use does not in any way prevent others from re-using this document in either original or modified form.