The Interface
Prev | Chapter 29. From Blender to YafRay Using YableX | Next

## The Interface

Relevant to Blender v2.31

The functions of Yable have been divided in three main screens, accessible by pressing the three upper buttons that you can see in Figure 29.2, “Yable header Buttons.”.

Figure 29.2. Yable header Buttons.

### Workflow philosophy.

Once we have created a Blender scene, with objects, materials and lights, we can load and start the script, possibly splitting the main 3D Viewport in two, and turning one of the two halves into a Text Window. This way we will be able to see at the same time the scene and Yable GUI.

The Yable Workflow is as follows:

- Select an object of the scene;

- Go to the Material or Light part of the interface, depending on what you are defining, and press the `Get Selected` button. This way Yable retrieves the settings for the object (if any);

- Edit the attributes. These are completely independent from those of Blender!

- Press the `Assign` button to assign the parameters you entered to the object. Don't forget this step! A button `Assign All` can be used to assign the data to all selected objects.

### Global Settings

This part of the GUI allows us to access the functions of general scene settings Figure 29.3, “Yable headerGeneral Setting Buttons.”.

Figure 29.3. Yable headerGeneral Setting Buttons.

- Texture path (Figure 29.3, “Yable headerGeneral Setting Buttons.”#5) - The path of the texture can be redefined anytime.

- Global Illumination (Figure 29.3, “Yable headerGeneral Setting Buttons.”#6) - Adds to the scene the global illumination, that is the simulation of the diffused light, originated in nature as an effect of the infinite mutual reflections and diffusions between the objects. Its effect is added to that any possible direct lights.

  Path light and Hemi light are finalized to yield of the same effect, but using different algorithms that have advantages and disadvantages, for the description of which we send back to the specific YafRay Chapter.

  Figure 29.4. Yable Global Illumination settings.

  Figure 29.4, “Yable Global Illumination settings.” shows the various options for Hemi or Path light. In the former case we can set up the colour using the `Red`, `Green` and `Blue` NumButton, or take the color from the background with the button `Use Background` color. It is possible to use this last feature when we use backgrounds based on images, even if the `Use Background` Button disappears by setting all the three RGB slider to 0.

  In the Path Light case, on the other hand, the background image is used by default. Another difference between hemi and path light is the `Depth` parameter, that is referred to the number of bounces to be considered in the calculation of the exchange of reflections between the objects. To get a minimum of radiosity effect it is necessary to have at least two light interchanges.

  Since the Path Light computation is rather complex a Cache option is provided, allowing to optimize and diminish the rendering times. It basically acts as a pre-process used to determine the zones of the image that need more samplings; as an example on a great flat surface we can presume that the diffuse lighting is quite uniform, and therefore we can carry out less calculations.

  Parameters shared by both the global lights are the Power, the QMC, and the Samples. The Power indicates the power of the luminous emission, while the Samples indicates the accuracy of the sampling during the rendering: high values improve the clearness of the light (the hemi light have the tendency to become grainy) but this increase vary much the times required for calculation. QMC refers to the use of the Quasi MonteCarlo method for the determination of the zones to compute: it is based on sequences of quasi random numbers, and accelerates the rendering, even if, sometimes, it generate granular pattern of the image.

- Background (Figure 29.3, “Yable headerGeneral Setting Buttons.”#7) - There are four options. Depending on the choice made some additional buttons appear, almost all are of immediate understanding (Figure 29.5, “Background settings.”).

  Figure 29.5. Background settings.

  The `Const BkGd`, is the easier to use (Figure 29.5, “Background settings.” top left): it is an homogenous colour defined by its RGB values.

  The `Normal BkGd` (Figure 29.5, “Background settings.” bottom right) allows us to use an image (the last version of YafRay supports JPG and TGA); the only parameter is the `Power`, that indicates the brilliance of the image.

  The `HDRI BkGd` (Figure 29.5, “Background settings.” bottom left) is, perhaps, the one allowing for the maximum realism. The HDR (High Dynamic Range) Images, by storing pixel colours as floating point numbers contain much more data than other formats. Moreover, they are usually available as probes, that is as full 360 horizontal, 180 vertical backgrounds. After the we have obtained the appropriate images, is necessary to put them in the same folder as the textures, to write the name in the `Probe Name` button, and to set up the exposure that we want to use (positive means brighter).

  Finally the `SunSky BkGd` (Figure 29.5, “Background settings.” top right) uses a sophisticated algorithm for the simulation of the conditions of Sun light. The position of the sun can be set by selecting an object in the Blender scene (usually an empty) and pressing the `Set Sun Pos` button and confirming. It is important to note that the dimension of the sun will depend also from the distance between the chosen object and the camera. A particularly important parameter for the construction of the scene is `Turbid`, that allows us to regulate the value of the density of the atmospheric layers that envelop the planet: dense layers let to go through only determined wavelengths of the solar light, hence it changes both the color and the power of the light. The other buttons control the halo and the spread of the beams. The SunSky background, if used with Path Light or Hemi Light, is able to emit light in extremely realistic ways. In the case in which we don't want to use Global Illumination we can press the Sun button and Yable will add a Sun type light in the exported scene, that will simulate, more roughly but faster, the effect of the solar light.

- Fog (Figure 29.3, “Yable headerGeneral Setting Buttons.”#8) - With the Fog slider we choose the amount of fog present in the scene (zero by default), while the color is chosen by selecting one of the three `Red`, `Green` and `Blue` button and by using the single Num Button below them (Figure 29.6, “Fog Settings.”).

  Figure 29.6. Fog Settings.

- Depth of field (Figure 29.3, “Yable headerGeneral Setting Buttons.”#9) - This is required to mimic a real camera's focal blur. This is a feature that YafRay will render in much shorter times than other rendering engines, as it is performed as a post-processing operation - however, this means that it has some shortcomings in the precise accounting of reflections.

  The regulation is made by selecting an object whichever in the scene of Blender and pressing the button `Set Focus` (Figure 29.7, “Depth of Field Settings.”). The point chosen in this way will be perfectly sharp. With the others two Num Buttons we can regulate the amplitude of the field depth: `Near Blur` influences on how much will the objects that are between the camera and the point of focus be blurred, while `Far Blur` affects the objects further than the focus from the camera.

  Figure 29.7. Depth of Field Settings.

- Anti-noise Filter (Figure 29.3, “Yable headerGeneral Setting Buttons.”#10) - This too is a filter applied as post processing. It works in an iterative manner by taking some points within of a circular area and assign the same color if their colours differ more than a given threshold.

  Figure 29.8. Anti Noise Filter Settings.

  The amplitude of the circular area is determined by the `Radius` parameter (Figure 29.8, “Anti Noise Filter Settings.”), while the threshold is given by `Max Delta`. This is a very useful filter, but to use with care, because it has also a blurring effect that might compromise the quality of the result. Higher values of the delta tend to unify all.

- Gamma correction, exposure, resolution (Figure 29.3, “Yable headerGeneral Setting Buttons.”#11) - A simple group of buttons that allows you to set the brightness and the gamma of the complete rendering. The `No` Buttons exclude completely both post-processes. The `Default` Button that bring back the `expos` Num Button to the default value. The `Gamma` Num Button allows the regulation of the gamma (Figure 29.9, “Resolution Settings.”).

  Figure 29.9. Resolution Settings.

  The resolution Menu Button allows you to choose the dimension of the rendered image. Pressing it, we can choose between the most common formats:320x240, 480x320, 640x480, 640x512, 768x470, 1024x576, 1024x768 and 1280x960. Choosing the `Custom` option, two new buttons are visualized, that allow to set up any resolution.

- Rendering setting (Figure 29.3, “Yable headerGeneral Setting Buttons.”#12) - This group of buttons allows you to set details of the exported file and let to launch YafRay directly from Blender (Figure 29.10, “Rendering Settings.”).

  Figure 29.10. Rendering Settings.

  The fundamental keys are `Export`, `Render`, `Filename` and `Image`. The last two are needed in order to choose the name that will have the XML file and the rendered image. `Export` produces only, within the `YABLEROOT` directory all the necessary XML files while, if used with `Render`, will also execute YafRay and will produce the final image; finally, if the button View Output is also selected, at the end of the rendering Yable will launch also the application specified in `VIEWERAPP`, in order to see the result. Note that you must have YafRay in your path to be able to launch it within Blender.

  The Layers button open a new panel for the choice of the layer to export (Figure 29.11, “Layer Selection.”).

  Figure 29.11. Layer Selection.

  The `Path` button forces the description of the scene to be exported using separate files (one main file, and sub-files to be saved in suitable folders, subdivided by materials and meshes). The location of such files will be indicated to YafRay by with the use of a full path.

  To the contrary, the `!INC` Button will force Yable to produce a "monolithic" file. If at the moment of the export neither `Path` or `!INC` are used, Yable will use automatically the `Path` option.

  ### Rendering problems

  Sometimes, by using different files, Yable incurs in some problems and may mix the objects created in previous rendering. In such case is worthwhile to use the single file, that is surely overwritten every time, or to delete the old XMLs.

  The `Anim` Button forces a `different` XML file to be exported for each frame of the Blender scene. Once the frames are rendered you can compose them into an animation by using Blender's Sequence Editor. The `Anim` button implies that the `Fr` (frame) button is also pressed, which appends to the chosen name for XML and images files a number suffix that indicates the rendered frame. All the XMLs are saved in a separate subdirectory named as the blender file with the `_MOVIE` suffix.

  ### An example

  Suppose our `YABLEROOT` is `C:/bar/` and we are working with the file `robot.blend`, when we press `Export`, Yable will create, first of all, a folder `C:/bar/robot/`; then, if we have specified the `Path` option, inside this directory the main XML file (called `robot.xml`) will be created, and two folders: `Materials` and `Meshes`, from which YafRay, reading the paths in `robot.xml`, will draw the data for the materials and objects.

  In the case in which we choose to use the `!INC` button, no folders will be created within `C:/bar/robot/`, but only a single file `robot.xml`, that contains all data.

  Finally, if the `Anim` button has been utilized, another folder will be created, `C:/foo/robot/robot_MOVIE/` containing as many XML `robot.001.xml`, `robot.002.xml`, `robot.003.xml`,... as there are frames in the animation.

  Note that if the files of the animation are obtained with the `Path` option, it will be necessary to copy the `Meshes` and `Materials` folders in the `robot_MOVIE` folder. If the animation does not include transformations of morphing (as an example RVK), is safe to leave de-activated the button `Update Mesh`. Otherwise for every exported frame every mesh of the scene will be exported too.

  The last three buttons are `GZ`, `Time`, and `alphaTGA`: the first enable the creation of gzipped files, the second let the time employed for the rendering appear on the YafRay console and the third modifies the XML so that YafRay saves TGA images with the alpha channel.

- Antialiasing setting (Figure 29.3, “Yable headerGeneral Setting Buttons.”#13) - `AAP` Num Button indicates the number of passes of antialiasing; putting it equal to zero indicates no antialias. `AAMS` adjust the number of samplings to use for every AA pass. `AAPW` adjust the pixel width parameter, that is the overlap of pixels; the range vary between 0 and 2, and using high values, we can obtains a better smoothness, even if sometimes too much accentuate. `AAT` establishes the value of threshold (`AA_threshold`) beyond which the pixel will be processed from the antialiasing: the value can vary between 0 (all points will be processed) and 1 (no pixel are processed). CPU indicates, if multiple CPU are present, how many should be used for rendering.

### Material Setting

The second GUI panel contains the Material Setting. Here it is possible to assign to every object the material that will be used in the YafRay rendering. The Materials assigned with Yable and Blender materials are two different things: the script draws from the scene only some values, like the UV coordinates and the diffuse color. This latter only upon request of the user. The rest is all independent; from this point of view Yable is a sort of laboratory: it not only exports passively the scene, but it allows us to study and to apply new materials.

Once an object is selected we must press the `Get Selected` Button: new buttons will appear; containing YafRay settings if the Object already has them, or empty otherwise(Figure 29.12, “Material Buttons.”).

Figure 29.12. Material Buttons.

- Shader Type (Figure 29.12, “Material Buttons.”#14) - This button allows you to choose the Type of Material Shader to apply.

  The `Constant` shader is the simplest, characterized only from the `Red`, `Green` and `Blu` Num Buttons. `Crafter` is a distinct case: it is an interface used to loading the Crafter shader, that is a stand alone program for the visual composition of materials. `Generic` is the more versatile material, and includes also the characteristics of the others, hence we will describe it deeply, using it like a paradigm for the general understanding.

- Object Attributes (Figure 29.12, “Material Buttons.”#14) - Pressing this button some new buttons appear (Figure 29.12, “Material Buttons.” on the right). They are very important characteristics, which are linked to the Object and not to the Material itself. The `Cast Shadow` toggles if the object projects shadows or not. The `Caustic IOR` button enables the calculation of the caustics for the light beams that will pass through the object; these will be deflected according to the value of the refractive index indicated from `CausIOR` NumButton. High IOR values produce more sharp caustics (think, as an idea, to the lens that concentrates the solar beams in a point). The `Receive Radio` and the `Emit Radio` buttons, if pressed, will force the object to participate to the calculation of the global illumination, receiving and re-emitting energy. The `Caustic Tcolor` Num Buttons allows you to specify the transmitted colour, that is the colour assumed from the light passing through the Object. The `Caustic Rcolor` Num Buttons, on the other hand, refers to the light reflected by the Object.

  ### Note

  Note that even if we set correctly a material, it will participate to the effects of caustics and radiosity only if it is illuminated with appropriate lights, like the Path Light, or the Photon Light.

- Diffuse Colour (Figure 29.12, “Material Buttons.”#16) - Is the basic color, and corresponds to the Diffuse Colour in Blender materials. The Bl button on the side is used take RGB values directly from the Blender Material. Pressing the button `Add Specular Color` new buttons appear similar to those just seen, used to set the specular color. Also in this case the meaning of this Colour is the same to that of Blender.

- Reflection and Transmission Colours (Figure 29.12, “Material Buttons.”#17 and #18) - It is possible to set the Reflected and Transparency colours of the material. Note that also the transparency is set using the RGB Num Buttons to define a Colour, not just a plain "alpha" value.

  The Transmit parameter does not decide the degree of transparency, but only which color of the light pass through (or is blocked by) the material. To make some example, using the black colour we impose that no color passes through the material, using the red one, we would mean that the object is transparent only for the red component of the light, using the white we let all the light to pass. Pressing also the buttons `Refl2` and `Transm2` which appears we can (and new RGB Num Buttons are created) define a different behaviour of the material at grazing light incidence.

- Hardness, Index of Refraction (Figure 29.12, “Material Buttons.”#19) - The `hard` parameter governs the sharpness of specular highlights exactly as in Blender. The refractive index `IOR` is fundamental in transparent objects, and is used in order to calculate the deviation of the light beams that crosses the material. As a result of this effect, the bodies immersed in a transparent medium appears to us distorted (think to a paddle immersed in the limpid water). Table 29.1, “Sample IORs” shows some IORs of common materials:

  Table 29.1. Sample IORs

  Material | IOR
  --- | ---
  Void | 1.0
  Air | 1.00029
  Ice | 1.31
  Water (at 20C) | 1.33
  Ethylic Alcohol | 1.36
  Glycerine | 1.473
  Glass | 1.52
  Sapphire | 1.77
  Diamond | 2.417

- Get Selected (Figure 29.12, “Material Buttons.”#20) - The `Get Selected`, to be pressed every time after you have selected the object and before starting to modify the material.

- Get Selected, Loading and saving the materials (Figure 29.12, “Material Buttons.”#21) - The `Load Material` and `Save Material` buttons allows you to save material settings and to quickly call them back. A name can be given to each material.

- Preview of the material, autosmooth and modulators (Figure 29.12, “Material Buttons.”#22) - The `AutoSmooth` Button is used to regulate the appearance of the surfaces. Pressing it an additional Num Button appears that regulated the angle under which the corner of the two faces is considered smooth, exactly as in Blender.

  The `Mat preview` Button creates a preview of the material using a sample scene. The tga is saved in the current directory (for example, under Windows, it is saved in the folder in which the Blender executable resides.) The button `phlightprv` indicate "Photon Light Preview" and it is used to put a photonic light during the materials preview.

  The `Modulators` Button allows you to access a separate panel for the composition of advanced shaders formed by overlying layers. Every layer can be an image or a procedural texture. Obviously is possible to set the modality with which the layers must be mixed and also the percentage of transparency.

  The panel at the beginning refers to the default modulators, that is used automatically if the Object has UV coordinates and is mapped with an image in Blender. Unfortunately, because of a bug, these formulations are not maintained by Yable, that continues to use the default settings. However all the successive layers of modulators that are added work correctly. In order to add a new component is sufficient to click on the Others button, and to choose the kind of modulator that we want. In Figure 29.13, “Material Modulators.” we see (starting from the top left, clockwise) the main panel, the panel adding new members, the menu `Others`, before and after the addiction of a new member:

  Figure 29.13. Material Modulators.

  It is possible to add an `Image` layer, a `Clouds` layer and a `Marble` one. The first thing is to assign a name at the modulator created, to do this it will be sufficient to write something of meaningful in place of `GIVE_ME_A_NAME`.

  If the Modulator is an image it is necessary to insert the name of the image itself: only the name and extension, without path, which has been defined once for all before!

  The parameters refer, by default, to bump mapping, that is to the relief effect that will be given to the object: using positive values rises clearer zones and lowers darker. The various size refer to the scaling of the UV coordinates (the three X, Y, Z axis may be scaled independently, or all together) while the various buttons `Col`, `Spec`, `Ref`, `Hard` and `Trans` have the usual meanings and indicates which characteristic, and by how much, is modified. At the end of the settings, press the `Ok!` button, to return to the main Material panel. At the end of the procedure the new added modulator will be in the Menu and can be selected and cancelled anytime, using the button `Del` that appear next to the `Ok!` `Canc` and `Back` buttons.

  ### Note

  The only type of mapping supported up to now is the UV type. It follow that the object must possess these coordinates, for which we sends back to the relevant Section of this Guide. If all is correctly executed, Yable will export automatically (without the adding of an image type modulator) both the UV coordinates and the used image. About this image we must pay attention to this: Yable does not use the image loaded in the texture of Blender's materials, but the one loaded in the Image Window (that is the one on which calculations for the positioning of the UV are made). Obviously, the images must all be in the usual folder specified at the start of the script.

  Clouds and Marble Modulators insertion is similar to that for the Images, except that these panels have few additional, self explanatory, specific parameters for these two types of procedural texture.

- Assign (Figure 29.12, “Material Buttons.”#23) - The `Assign` button finalizes the material and assigns it to the object. Don't forget this! The button Selected All allows you to assign the settings to more than one selected objects.

  ### Note

  Saving a material and Assigning a material are two separate actions. If you assign it the Object acquires that material, if you save it, it will be available later on.

### Light Settings

The lights setting in Yable is made with the same modality of the materials assignation: a light is selected in Blender, `Get Selected` is pressed and the characteristics that we want to to export in YafRay are chosen and assigned definitively with `Assign`.

The type of light used in the scene of Blender do not have any relationship with the type of light that will be exported: the only parameters that will be surely conserved are the positional coordinates of the lamp; all the rest, included the pointing direction can be assigned independently with Yable. In Figure 29.14, “Light GUI Panel.” we have represented a point light with the buttons Diffuse and Caustic activated, so to have an example that include the greater part of the available options.

Figure 29.14. Light GUI Panel.

- Light Types (Figure 29.12, “Material Buttons.”#24) - The menu lets us choose between various types of direct light: `Point Light`, `Spot Ligth`, `Soft light`, `Area Light` and `Photon Light` . Accordingly to the light type the options immediately beneath varies. Figure 29.15, “Direct Light Options.” shows them all.

  Figure 29.15. Direct Light Options.

  The Point light is a point source that emits light in all the directions. The power of the lamp is chosen with the `Power` Num Button, while its colour is set via RGB Num Buttons and is possible to choose if it must project or not a shadow with the `Cast Shadow` Button.

  The Spot light is very similar to the Blender spot: the parameters `Blend` and `Falloff` have the same meaning, while `Width` represents the angular width of the light cone.

  `Halo` indicates the presence of the halo (volumetric light), by pressing it we add some new buttons: three Num Buttons for the Halo colour, `Res` = resolution of the shadow map, `Density` = quantity of fog contained in the halo, `Blur` = blur applied to shadow map, `Samples` = number of samplings used in the rendering.

  The direction of the Spot is given via a target. We must press the `Select Target` button, select an Object to be the target of the spot in the Blender scene and finally press the `Confirm` Button to complete the operation.

  Both the Point and the Spot light decreases following the physical law of the inverse square of the distance.

  The Soft light is similar to the Pointlight, with the difference that it produces soft shadows. Shadows which appear to be too "clean" are one of the disadvantages of the raytrace engines, but this type of light, using a shadow map, safely resolves the problem. Besides the usual parameters, the `Radius` parameter, defines the width of the transition between shadow and light. The `Bias` parameter controls the proximity of the shadow to the object that produces it, while the `Resol` parameter controls the resolution of the shadow map: the higher is this parameter the better is the accuracy of the shadow.

  The Sun light simulates the characteristic of the solar light, it seems not to decay with increasing of the distance (it is an impression due to the enormous power of the Sun). It is, therefore, a much simple light, in which we can only set up the color, and whose intensity remains constant.

  The Area light is an extended luminous source. While all those already seen emit light from a point (in reality it corresponds, as an example, to the small filament of a light bulb), the area light is produced from a whole surface. YafRay admit also quadrilateral surfaces but Yable is limited to use only squares. The specific parameters are `Samples`, `Psamples` and `Side`, they are the number of general samplings, the number of samplings in the penumbra zone, and the length of the side of the light casting square.

- Photon Lights (Diffuse and Caustic) (Figure 29.12, “Material Buttons.”#25 and #26) - Photonlight is a very peculiar kind of lamp: it behave in a more realistic way, referring itself to the theory of the light composed by a bundle of photons. These photons must literally be "shoot" towards the Objects, so as to calculate their behaviour when they travel through transparent bodies or are diffused by opaque ones. It is a very complex calculation, for which is not always desirable that it will be executed on all the elements of the scene; therefore we can specify it on a material to material and object by object basys via the parameters Receive and Emit.

  Diffuse light: Enabling this button a Photon Light of Diffuse type will be add to the exported scene, overlapping the corresponding Direct light. The photons of this light have the capability to be reflected on diffusive surfaces. In this way calculations of the radiosity 'colour leakage' will be added in the rendering, to realize a realistic effect of Global Illumination. This can be done also via Path Light, but a carefully tuned Photon Light is much faster.

  Caustic light: Caustic are concentrations of light caused from the refraction of the transparent objects. The Photon Light of Caustic type allows you to account for this phenomenon correctly. Before going ahead, it is necessary to say that if targeted to objects with inadequate material, this light does not generate any effect. In fact the scene, to have caustics, must contain a source light A, an opaque object C receiving the caustics and a transparent object B placed between these two generating the caustics (Figure 29.16, “Caustics setup.”).

  Figure 29.16. Caustics setup.

  - A must be a caustic photonlight;

  - B must have a Material able to produce Caustics (exhibiting at leastassigning at least Caustic IOR and Caustic Tcolor);

  - C must have a Material able to receive the radiosity effects (for this the default material could be good, because this material export a simple shader that, without specify the received and emitted values of radiosity leave the choice to YafRay, that usually hold this values activated. If, indeed, a generic material is used, we must remember to activate the `Reiceve Radio` Toggle Button).

  The Photon Light of Caustic and Diffuse type have the same parameters. The arrows button is used to impose the same value to more than one variables (for example the same color ).

  The `Photons` button set the number of photons that will be shot from the lamp, in common scene a few thousands of photons is enough but, to obtain a better results in terms of quality is recommended to set 50000 photons or more. The `Depth` button defines the number of bounces/transmissions the photons can do before YafRay ray tracing stops to handle it, and it is a particularly important data, mostly in the calculation of the Global illumination. 3 is a good value for acceptable results. `Search` indicates the numbers of photons that can be used to illuminate a single point of the Object surface, higher values is used to take in consideration also zones that receive few photons, with a shaded effect of illumination, while low value is used to give light only to the points really hit by photons completely, with more definite and "hard" boundaries. `Angle` is the angle of the projection cone with which the photon are shot: high values are used to cover a wide area, but with power fading when we depart from the center. `Fixed` is the abbreviation of fixedradius, and represent the radius in which the number of photons defined by `Search` must fall in order to consider the point of the surface illuminated. `cluster` is the smallest portion of lit surface able to contain a photon. The higher is this number the larger is the width of the cluster and, consequently, the less defined is the illumination effect. `QMC` is, again, the quasi-MonteCarlo method.

Prev | Up | Next
Installing the script | Home | Yable Juicy example