An understanding of POV-Ray Arrays is handy because arrays are used extensively within POV-Person.
Tip: The POV-Ray help files cover all of these topics, just look up 'identifiers', 'macros' and 'array' in the index.
Warning: If you don't have at least a rudimentary understanding of these topics then you will probably find it difficult to understand the explanations given in this users guide.
If you are intending to use the animation features of POV-Person you will need an aptitude for the subject. Animation is not considered suitable for the novice user or for the faint hearted.
POV-Person provides a series of macros and include files that should enable you to add a range of different figures to your POV-Ray scene files within minutes. However, it probably won't be long before you want to go further than simply using the figures provided. After all, life would get pretty dull if all of the images everyone generated contained only a standard cast of characters. POV-Person has therefore been designed to enable and encourage modification and extension.
You get access to all of the source used to generate a figure and can modify it in any way that pleases you. Some of the techniques used are relatively complex and potentially overwhelming to novice users. The library has therefore been structured into a series of layers and components that enable novice users to tailor their figures using a comprehensive set of control variables while more experienced users can readily add or replace elements or groups of elements. Advanced users should be able to adjust the supplied macros or incorporate new macros to suit their own needs. Some of the POV-Person macros potentially have a broader use than the use to which they have been put here and have been written in a generic way to encourage re-use in a diverse range of circumstances. For example, the ppCrowdPosition macro defines a series of random positions on a POV-Ray object. In POV-Person it is used to position individual members of a crowd, but could potentially be used to position other objects on a surface of your choice.
It is anticipated that different people will want to do very different things with the library. The library and this documentation have therefore been structured so that you do not have to learn all about POV-Person, you can just focus on the bits that will enable you to address the unique and imaginative challenges of most interest to you.
For this reason there are various ideas dotted around in the source for you to play with. For example, alongside the more realistic skin textures there are examples of a semi-transparent green skin texture and a spiral texture (that produces an Escher like effect). If you like playing with textures it's easy to add your own without necessarily having to learn all about POV-Person.
Alternatively you may be interested in replacing individual components such as the eye object or groups of objects such as a hand with your own definitions. To do this you don't necessarily have to learn about textures.
You can also define entirely new types of figures, by using existing body parts, body parts you define yourself or any combination of the two.
It is recommended that you read through the next short sub-section 'How POV-Person works' to get an idea of the structure of the library then decide what you want to achieve and dip into the different sections of the document as you need.
Many of the names used within the POV-Person library have a global context and using a consistent prefix is intended to minimize potential conflicts with names that you use in your scene files.
You should treat all names beginning with 'pp' as reserved words and avoid defining your own names with this prefix. As well as avoiding immediate conflicts that can be difficult to understand and track down, this policy will also help to protect you against conflicts with names used in future releases of POV-Person.
The ppFigure macro doesn't actually do very much itself, it just controls the sequence of activities necessary to build the figure defined by the parameters and control variables you specify. Most of the parameters you pass it are in the form of file names that identify include files that will be used to control different aspects of the figure.
The first parameter passed to the ppFigure macro points to the Character file. This file contains essential control variables that define the underlying model from which the figure will be built as well as different groups of components from which the figure should be constructed. For example, to use the 'Alf' character you would specify the ppalf.inc file as the first parameter to the ppFigure macro. The ppalf.inc file specifies that Alf is based on the human001 model and sets a number of control variables that will be used to construct the 'Alf' character.
POV-Person performs a lot of its work using a series of arrays that are normally only manipulated through the various POV-Person macros. For example, body parts that make up the specified model are assigned to an array of objects using the POV-Person ppAddBodyPart macro. The relationship between these body parts is established using the POV-Person ppAddJoint macro.
The include file for the human001 model therefore uses the ppAddBodyPart macro and the ppAddJoint macro to define the anatomy that constitutes the human001 model. In the process it records a set of references that are returned from the macros which can subsequently be used to manipulate the model.
Part of this manipulation is performed in the include file identified by the 'Pose' parameter of the ppFigure macro. This file contains a sequence of calls to the ppRotateJoint macro which populates a core control array with a rotation vector for each joint. This vector specifies the joint rotation as a sequence of three single axis rotations where the three axes used are specific to the joint being manipulated (as defined using the ppAddJoint macro).
Other include files passed to the ppFigure macro control refinements to the model, such as makeup, hair style and colour.
Control Variables
The simplest way to create a unique look for a person in your scene file is to adjust the control variables exposed by the POV-Person library files. The convention for POV-Person control variables is that their names begin with 'pp'. In general if you avoid using variable names beginning with 'pp' for your own purposes it is likely that you will avoid variable name conflicts with the current and any future versions of POV-Person.
Control variables can be defined inline in your scene file before calling the ppFigure macro or within include files accessed by the ppFigure macro. Control variables are grouped within include files with the principal groups being used to specify the 'character', the 'style' and the 'pose'.
With many of the control variables it is clear which grouping they fall into. For example the definition of the face, lip and hairline objects are specified as part of the character whereas the hair style and hair colour are defined as part of the 'style' group. In some cases the default grouping differs by gender. The 'ppLipColour' variable is set in the 'style' file for females (assuming that it will generally be defined by their lipstick colour) and in the 'character' file for males (assuming that the lip colour for men is more commonly a natural colour). Some variables are clearly style controls but the male and female styles may differ. For example, ppHairLength and ppFringeHairLength can be adjusted differently for males and females, consequently they are set in the gender specific sections of the control files. Another example is a bearded style, which is usually only applied to the male definitions.
Resetting character attributes
Many of the attributes of a POV-Person character can be set in your scene file before calling POV-Person. To support this, POV-Person checks to see whether a control variable exists before setting the value it would normally set. As a consequence, calling POV-Person a second time to generate a second character could result in certain attributes being carried across from the first POV-Person macro call.
This will usually be something that you want to avoid. A macro is therefore provided that clears down the control variables and character matrix variables ready for the definition of a new character. If you have stored the first character as a named object, then you can still use that character later in the scene file, even after resetting the variables originally used to define it.
Reserved Words
POV-Person uses a large number of control variables and a series of macros to generate a character. Many variable and macro names have a global context, so to avoid conflict with variable and macro names that you may wish to use in your scene file, all POV-Person variable and macro names start with 'pp' (for POV-Person). All variable and macro names starting with 'pp' are therefore reserved words when using POV-Person. That is to say that you should not use the 'pp' prefix to name any other variables or macros used by your scene as it may conflict with variable names or macro names used the current version of POV-Person or by any future versions of POV-Person.
Reserved File Names
POV-Person also uses the 'pp' prefix for file names. You should avoid using the 'pp' prefix for any other files as this will help reduce conflicts with other POV-Ray libraries.
Exceptions
If you are adding new files, control variables or macros that you are intending to submit for future inclusion and public distribution in the POV-Person library then you should use a variation on the POV-Person naming conventions for your work. The convention recommended is to use a prefix of 'ppNNN' where NNN is a 3 digit number of your choosing. The purpose of this 3 digit number is to uniquely distinguish all of your files, control variables and macros from those of anyone else. Once you have chosen a 3 digit number you should use the same number for all of your new files, control variables and macros.
Technical Overview
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.
Next you can either read about these options in the remainder of this documentation or just dive in and try a few things for yourself.
Control variables can be defined inline in your scene file before calling the ppFigure macro or within include files accessed by the ppFigure macro. Control variables are grouped within include files with the principal groups being used to specify the 'character', the 'style' and the 'pose'.
With many of the control variables it is clear which grouping they fall into. For example the definition of the face, lip and hairline objects are specified as part of the character whereas the hair style and hair colour are defined as part of the 'style' group. In some cases the default grouping differs by gender. The 'ppLipColour' variable is set in the 'style' file for females (assuming that it will generally be defined by their lipstick colour) and in the 'character' file for males (assuming that the lip colour for men is more commonly a natural colour). Some variables are clearly style controls but the male and female styles may differ. For example, ppHairLength and ppFringeHairLength can be adjusted differently for males and females, consequently they are set in the gender specific sections of the control files. Another example is a bearded style, which is usually only applied to the male definitions.
The hair is added to a figure in the same way that other body parts are added to a figure. This means that it is easy to replace the hair macros with more sophisticated hair generation macros or custom hair objects.
When developing figures and scenes it is often usefull to work with a simple hair style, such as ppstyle4 or ppstyle7 that render quickly, then to replace the hair for the final render.
POV-Person includes a short hair macrso (see ppshorthair.inc) that incorporates an algorithm for 'growing' hairs on a surface. The hairs are made using a section of a torus.
There is also a similar macro (see ppxxxxxxxxx.inc)that combines 2 sections of a torus to provide more curves along the length of the hair.