Yafaray Scene XML Programming

Purpose: To Explore the Yafaray Scene XML.

Target Audience: Everyone who is interested in exploring the elements of Scene and Especially the Yafaray Scene, for the programming purpose or its integration with any other 3D Software, like With Blender of www.blender.org.

Source/Example File: http://tutorials.manojky.net/yafaray/test%20transpshadows.blend

Below is the XML Generated From Above Scene is:

<?xml version="1.0"?>

</material>

<absorption_dist fval="85.9466728122"/>

<dispersion_power fval="2499.61673555"/>

<fake_shadows bval="false"/>

<filter_color a="0.775566148236" b="0.351314" g="0.78044244" r="0.030511"/>

<mirror_color a="0.465472321929" b="0.8891386" g="0.55429" r="0.422366133405"/>

<transmit_filter fval="0.220283180581"/>

</material>

</light>

<bokeh_rotation fval="0"/>

<bokeh_type sval="disk1"/>

<dof_distance fval="0"/>

</camera>

<set_material sval="defaultMat"/>

</mesh>

<set_material sval="TestMat"/>

</mesh>

</background>

<AO_color r="1" g="1" b="1" a="1"/>

<AO_distance fval="1"/>

<AO_samples ival="32"/>

<do_AO bval="true"/>

</integrator>

</integrator>

<AA_inc_samples ival="1"/>

<AA_minsamples ival="2"/>

<AA_passes ival="2"/>

<AA_pixelwidth fval="1.5"/>

<AA_threshold fval="0.05"/>

<background_name sval="world_background"/>

<camera_name sval="cam"/>

<clamp_rgb bval="false"/>

<filter_type sval="mitchell"/>

<integrator_name sval="default"/>

<volintegrator_name sval="volintegr"/>

<z_channel bval="true"/>

</render>

</scene>

Exploration:

Default XML Tag:

<?xml version="1.0"?>

The above mentioned tag will always present an any XML file so you can ignore it, I mean DO NOT TOUCH.

Root Element:

</scene>

The above mentioned tag is the Root Element of the Scene, so Please DO NOT TOUCH.

As you know that the Root Element is the parent and it can not have its parent. i.e. it’s the eldest guy here J.

The Child/Children Material:

</material>

The above mentioned tag is the Material Tag, all the material specifications are made in this tag. It has an attribute “name”, (so that the parent can identify it J)

Below is the typical example of a Glass material:

<absorption_dist fval="85.9466728122"/>

<dispersion_power fval="2499.61673555"/>

<fake_shadows bval="false"/>

<filter_color a="0.775566148236" b="0.351314" g="0.78044244" r="0.030511"/>

<mirror_color a="0.465472321929" b="0.8891386" g="0.55429" r="0.422366133405"/>

<transmit_filter fval="0.220283180581"/>

</material>

Well here you have got someone to play with, i.e. you can play with all the numerical values with in the specified range, i.e. for r,g,b and a its between 0 and 1. You can even play with “bval” (Boolean Value) either “true” or “false”. Similarly “fval”(Floating point Value), but before playing with “fval” try to get the range of the specified “fval”. I believe rests of the tags are self-explanatory.

The Child/Children Texture(Not present in example):

</texture>

Here is an optional child J , like other child it has a name attribute so that it can be identified by other elements I mean this child is which is called by the material child by the tag :

<list_element>

</list_element>

</material>

So you might be wondering “What I can play with in my programs?”. Well here you have amazing options of playing with, before moving to the play options is to be careful about

<texco sval="orco"/> tag (Importance will be explained with “mesh” tag) consider following example:

<calc_alpha bval="false"/>

<cropmax_x fval="1"/>

<cropmax_y fval="1"/>

<cropmin_x fval="0"/>

<cropmin_y fval="0"/>

<use_alpha bval="true"/>

</texture>

Play with <filename sval="c:\test.jpg"/> for changing the image for textures. Again do what ever you want with the numerical values by staying in limitsJ.

The Child/Children Light:

</light>

So here is your child who spreads light, I think by now you know what you can play with here. Play with all the numerical values but be careful with the “<direction”, as you scene might go blind if you give wrong directions.

The Child/Children Camera:

<bokeh_rotation fval="0"/>

<bokeh_type sval="disk1"/>

<dof_distance fval="0"/>

</camera>

This child is your eye, as its clear by the name its Camera and does exactly what it does in real world, i.e. capturing. So your playing rules are same but be careful with all the parameters, and I would suggest that try avoiding playing with this guy. And this is called by the <render> tag, obviously by its name.

The Child/Children Mesh:

<set_material sval="defaultMat"/>

</mesh>

I think this child is center of attraction for those who are into the field of Optimization, Science, Math and Engineering of the Shapes. This child is special yet it does not have a name tag, it is identified by its presence in the scene, i.e. if you remove this child the parent wont mind and still you can render, its not the case with those child who have names, because if you remove a child who has a name, the rendering engine is likely to crash as it might have been called by some other child.

Coming back to <mesh>, it has attribute “vertices” which tells the engine how many tags are present, i.e. for avoiding a loop in render to count the points/coordinates and similarly the “faces”. This calls the <material> child by its name like this” <set_material sval="defaultMat"/>”. You need to be careful with the attribute has_uv="false" while using textures.

Attention Progamming guys, below is the Python code to produce Yafaray mesh from a simple Wavefront (.obj) models:

#*************************Start of Code ********************************

######################Copyright Info#####################################

#Author: Manoj Kumar, Email: hemuman@gmail.com, Web: http://manojky.net

#Retain this tag while copying this program just to remember from where you got this J

#before replicating code for distribution please drop a mail to hemuman@gmail.com

# as an information.

#######################################################################

from xml.dom import minidom

from xml.dom.minidom import Document

import os, sys

import re

doc = Document()

mesh=doc.createElement("mesh")

doc.appendChild(mesh)

mesh.setAttribute("has_orco", "false")

mesh.setAttribute("has_uv", "false")

mesh.setAttribute("type", "0")

#<mesh vertices="424" faces="322" has_orco="false" has_uv="false" type="0">

f=open(sys.argv[1], 'r')

f_xml=open(sys.argv[2], 'w')

vert_num=0

vert_flag='true'

face_num=0

face_flag='false'

set_mat_flag='true'

for line in f:

#print line

vert = re.split(" ",line)

for ver in vert:

if ver == 'v':

vert_num=vert_num+1

vert_flag='true'

face_flag='false'

if ver == 'f':

face_num=face_num+1

face_flag='true'

vert_flag='false'

#print ver

if vert_flag=='true':

v = doc.createElement("p")

v.setAttribute("x", vert[1])

v.setAttribute("y", vert[2])

v.setAttribute("z", vert[3])

mesh.appendChild(v)

if face_flag=='true':

if set_mat_flag=='true':

set_material = doc.createElement("set_material")

mesh.appendChild(set_material)

set_material.setAttribute("sval", "defaultMat")

set_mat_flag='false'

f = doc.createElement("f")

f.setAttribute("a", str(int(vert[1])-1))

f.setAttribute("b", str(int(vert[2])-1))

f.setAttribute("c", str(int(vert[3])-1))

mesh.appendChild(f)

print 'No of Vertex',vert_num

print 'No of Faces',face_num

mesh.setAttribute("vertices", str(vert_num))

mesh.setAttribute("faces", str(face_num))

#<set_material sval="defaultMat"/>

#print doc.toprettyxml(indent=" ")

f_xml.write(doc.toxml())

f_xml.close()

#***********************End Of Code ************************************

Again be careful with the mesh types while converting from Wavefront to Yafaray Mesh, as the Yafaray engine can use Triangular and Universal types. Although the code will simply convert to the Yafaray format (Trinagular type), and it does not verifies for the pit falls.

Well again you might be expecting a code for other way around, so here it is:

#*************************Start of Code ********************************

######################Copyright Info#####################################

#Author: Manoj Kumar, Email: hemuman@gmail.com, Web: http://manojky.net

#Retain this tag while copying this program just to remember from where you got this J

#before replicating code for distribution please drop a mail to hemuman@gmail.com

# as an information.

#######################################################################

from xml.dom import minidom

import os, sys

f=open(sys.argv[2], 'w') #name of the obj file

xmldoc = minidom.parse(sys.argv[1]) #name of the yafray xml

mesh = xmldoc.getElementsByTagName('mesh')

#print mesh[0].toxml()

vertex=mesh[0].getElementsByTagName('p') #vertex of first mesh

for vert in vertex:

x=vert.attributes["x"].value

y=vert.attributes["y"].value

z=vert.attributes["z"].value

f.write('v '+x+" "+y+" "+z+"\n")

#print vert.attributes["x"].value,vert.attributes["y"].value,vert.attributes["z"].value

face=mesh[0].getElementsByTagName('f') #face of first Mesh

for fac in face:

a=int(fac.attributes["a"].value)+1

b=int(fac.attributes["b"].value)+1

c=int(fac.attributes["c"].value)+1

f.write('f '+str(a)+" "+str(b)+" "+str(c)+"\n")

f.close()

#***********************End Of Code ************************************

Above will code do exactly what you expect it to, here the code takes the first mesh, if you are familiar with the python you can modify code for all the mesh in the scene.

The Child Smooth:

Play with that angle to see what you get.

The Child Background:

</background>

Play with the numerical values.

The Child Integrator:

<AO_color r="1" g="1" b="1" a="1"/>

<AO_distance fval="1"/>

<AO_samples ival="32"/>

<do_AO bval="true"/>

</integrator>

</integrator>

Well you need to read the actual specification for integrator.

The Child Render:

<AA_inc_samples ival="1"/>

<AA_minsamples ival="2"/>

<AA_passes ival="2"/>

<AA_pixelwidth fval="1.5"/>

<AA_threshold fval="0.05"/>

<background_name sval="world_background"/>

<camera_name sval="cam"/>

<clamp_rgb bval="false"/>

<filter_type sval="mitchell"/>

<integrator_name sval="default"/>

<volintegrator_name sval="volintegr"/>

<z_channel bval="true"/>

</render>

This is the child who controls every one in the family, and it calls the Camera “<camera_name sval="cam"/>”, integrator “<volintegrator_name sval="volintegr"/>”, I would suggest you to play with these parameters when you become expert with all the children.

Conclusion:

Well, nothing to add in the end, just this:

Yafaray is a great rendering engine and try utilizing the freedom of its XML format with the programming and specially people in research fields of Shape related Optimizations can use this great Rendering Engine to give a final look to your surface and scene. I am myself, is working towards the integration of Yafaray with mk3D, i.e. my own 3D software which is under development and along with Pro/E an excellent product form PTC (Parametric Technology Corporation) for Modeling and Analysis.

By-Manoj Kumar

Email: hemuman@gmail.com

Web: http://manojky.net

************************************************************************************

******