How to use PovEdge - version 1.02
----------------------------------------------


SUMMARY :
	I) 	Basic use  (read this for a quick start)
	II)	Fine Tuning
	III)	F.A.Q


NB : Look also at the demo scene for a practical example.

Basic use:
++++++++++

	1) Chose your input file, which contains one or several mesh2 declarations.
	1b) By default, the output directory is the one of the input file. You can
	    change it if necessary
	
	2) Press the "Run" button. The program will parse the input file, and for each
	   mesh2 declaration, il will output the 2 files needed by the edge macro.
	   After that it will create a file called "declarations.inc", which contains
	   all the declarations needed to draw the edges, and will also put a copy of 
	   the macro include in the output directory. The object containing the union
	   of all edges is simply called "Edges". (If you check the box  "Add filename",
	   the name of your input file will be added to the "declarations" and "Edges",
	   thus giving "declaration_myfilename.inc" and "Edge_myfilename". This is useful
	   if you need to run PovEdge on several files for the same scene.)
	
	3) Things you need to add to your pov scene to have the edges drawn:
	  
		a) You MUST DEFINE the point of vue, which is the location of the
		   camera, as "PdV" (it is a good idea to define it before declaring
	 	   the camera, and having "location PdV" in the camera block)

		b) You MUST DEFINE the "effective" point of vue, "PdV1". If you apply
		   no transformation to your mesh objects, then simply PdV1=PdV.
		   However, if you apply a transformation to your mesh objects, PdV1
		   is obtained from PdV by applying the inverse transformation. 
		   Don't forget that the inverse transformation of a combinations of
		   transformations is obtained by applying the inverse transformations
		   in *reverse order*.	For example, if you apply a rotation and then
		   a translation to your meshes, you must first apply the inverse 
		   transltion to PdV, and then apply the inverse rotation. See the 
		   example below.

		c) You probably need to change EdScale and EdNScale, depending on the 
		   scale of your scene. These are scaling factors for the width of the
		   edges, so increase it/lower it if you need wider/thiner edges.
		   If you do not define them, the default values for EdScale and EdNScale 
		   are 1.0. You can also change the value of "EdThresh", which is the 
		   threshold for the crease edges. A value of 0 means no crease edges, and 
		   a value of 1 means all edges are drawn as crease edges. Typical values are
		   in the 0.6-0.8 range, depending on your mesh. The finer your mesh, the larger
		   EdThresh can be before getting artifacts. If you do not define it, the
		   default value is 0.6.

		d) You can now include the file "declarations.inc", and add
		   object{Edges xxx} to get the edges, where xxx is the transformation
		   you have applied to your mesh objects. You need also, of course, to put
		   in your scene your mesh objects. If you want a toon/cel-shading look,
		   use for the textures of your meshes plain color with some ambient and
		   low brilliance. If you want the edges only (but with hiding of the edges
		   which have to be hidden), put a uniform background in your scene (for example
		   #background{ rgb 1}, and put pigment{rgb 1} finish{diffuse 0 ambient 1} for
	 	   all the textures of your meshes.

		e) This should be enough to have the edges of the different meshes 
		   declared in the input file. See the section "fine tuning" below
		   for more options and a better control of the edges.



Example of PdV1 when applying transformations:
++++++++++++++++++++++++++++++++++++++++++++++

	Suppose you apply the following transformation to your mesh:
	"scale <sx,sy,sz> rotate y*Yrot translate <tx,ty,tz>"

	Once PdV is defined as the camera location, you must define PdV1 as:
	PdV1 = PdV - <tx,ty,tz>;        		//inverse translation
	PdV1 = vrotate(PdV1,<0,-Yrot,0>); 		//inverse rotation
	PdV1 = <PdV1.x / sx, PdV1.y / sy, PdV1.z / sz>; //inverse scaling

	Note that if you apply different transformations to the different meshes
	declared in your input file, you must define a different PdV1 for each
	mesh. To do so, edit the file "declarations.inc", uncomment the line
	"PdV1 = PdV;"  which is right before each macro call, and define PdV1 as needed
	before each macro call.

	
Fine tuning:
+++++++++++++

	Basically, if you want a better control, have a look at the contents
	of the file "declarations.inc". Things should be more or less
	self-explanatory. You can for example:

	- apply different contour widths to the different meshes. To do so, edit 
	  the file "declarations.inc", and modify the width declared for
	  each object before its macro call. This is very usefull if you
	  have meshes with very different sizes.

	- apply different thresholds to the different meshes. This is done	
	  also by editing the file "declarations.inc", and changing the
	  parameter EdThresh before each macro call.

	- apply different colors to the different meshes. The textures
	  for the edges are defined in "declarations.inc".Colored edges (non black)
	  can be classy ! 

	- remove some edges from the union defining the objet "Edges". 
	  To do this, simply comment some lines in the declaration of
	  Edges, at the bottom of "declarations.inc". This is useful
	  to remove for example creases edges for certain meshes.

	- In addition, there is another parameter which was not described yet:
	EdBorder. When a mesh object is not closed, or when it has holes, there
	are edges which are not shared by two faces and which form the border
	of the mesh. When EdBorder is 1 (default value), those edges are plotted.
	If you declare EdBorder as 0, then those edges are not shown. Removing the
	border edges can be usefull sometimes.



III) F.A.Q.:
+++++++++++++

	Q/ How can I get several copies of my mesh objects, with correct edges
	  for each copy ?

	A/ As the different copies will be at different positions, they need to
	   use different effective point of vue (PdV1 parameter). If you need a copy
	   of all the meshes of your input file, just copy the file "declarations.inc"
	   with another name, change there the name of "Edges" (for example "Edges2").
	   Then, in your scene, define the correct PdV1 for the copy before including
	   the modified declaration file and add the second Edges object. 
	   If you just need a copy of one of the meshes of your input file, you can also
	   simply copy the macro call for this object in "declarations.inc" (with the 
	   correct PdV1 defined right before the macro call), change the names of the objects
	   created by this macro call, and define another "Edges" object (say "Edges2")
	   which contains the output objects of this macro call.


	Q/ I can't get the crease edges right: with a low EdThresh I get none, but if I increase
	   EdThresh I immediately get artifacts.

	A/ Crease edges can be difficult to get right sometimes, specially with low-poly meshes
	   (because in a low-poly mesh, the angle between two neighbourhing face is quite large
	   even for smooth parts of the mesh, where crease edges should not be present).
	   A solution can be simply to subdivide the mesh; this can be done with Poseray.


	Q/  Why is it interesting to use Poseray together with PovEdge ?

	A/  Poseray can be really useful (and I am not linked in any way with Poseray author)!
	    Not only can it convert many 3d formats to mesh2 (and this is compulsory to use PovEdge),
	    which allows to use many models found on the internet,
	    but Poseray can also be used to mend/improve the model. It can be useful sometimes to
	    weld the model (this is done in the "Groups" tab, check "Weld vertices" and then click
	    "update"). Sometimes, the model normals are not correct, and Poseray can re-calculate the
	    correct normals (with "Calculate normals", right above weld). And Poseray can also subdivide
	    the model, which can improve a lot the smoothness of the edges and the quality of crease edges.
	    Note that Poseray can even import the mesh2 format, so those operations can be done even if you
	    have only the .inc povray file!


	Q/ When I use toon shading textures with low brilliance, I get strange shadows (the borders of the
	   shadows are jagged).

	A/ This is an annoying problem which is specific to the combination of mesh and low or zero brilliance.
	   It can be fixed by subdividing the mesh, to get a smoother border between shadowed and non-shadowed parts.


	Q/ How does the macro compute the edges ?

	A/ The idea behind the macro is quite common, and can be found on the internet. Two different
	   kinds of edges are computed. The first type is the "silhouette edge", which gives the outline of the
	   object. This edge is precisely the frontier between the part of the object
	   that is visible and the part that is hidden. So, if we have a mesh object (an ensemble of
	   vertices, joined by edges, forming triangular faces), it is easy to see if a given edge joining
	   two vertices belongs to the silhouette contour or not: just look at the two faces sharing this edge,
	   and if one is visible while the other is hidden, then this edge belongs to the silhouette contour.
	   The visibility of a given face can be checked easily by looking at its normal vector (it is visible
	   if the normal vector is pointing towards the camera). The silhouette depends of course on the relative
	   position of the camera and the mesh object.

	   The second kind of edges are "crease edges", which show the abrupt changes of orientation of faces.
	   To see if a given edge, joining two vertices, is a "crease edge" , just compare
	   the orientation of the normals of the two faces sharing this edge, and if the difference
	   of orientations is larger than a given threshold, then the edge is a "crease  edge"

	   Note that, in order to test whether a given edge belongs to the silhouette, or is a crease edge,
	   one need to know the "edge structure" of the mesh, which tells for example that the edge
	   joining vertices x1 and x2 is shared by faces y1 and y2 (x1,x2,y1,y2 are arbitrary numbers).
	   This information is not included in the mesh description that povray uses, and has thus to be 
	   computed first. This is done by PovEdge, and the result is contained in the xxx_edge.inc files.
	