From Kraytracing Wiki

Contents 1 About Commands 2 Header commands 2.1 var __blendss 2.2 var __undersample_edge 2.3 var __overrideflag 3 Tailer commands 3.1 recurse 3.2 octree 3.3 octsmallcube 3.4 octbuild 3.5 octshow 2 4 Other commands 4.1 about 4.2 cam_singleside 4.3 debug "debug_flags" 4.4 echo "text" 4.5 include "filename" 4.6 lmimportance "importance" 4.7 logfile "filename" 4.8 lwtransoptions sideness_mode,color 4.9 limitdr 4.10 mipmap "filter_size_shift,additional_samples,minsamples,maxsamples" 4.11 octstats 4.12 octsmallcube ratio 4.13 photons_singleside 4.14 postprocess 4.14.1 postprocess add,(r,g,b) 4.14.2 postprocess ca,strength,aspect_ratio,distance_influence,samples 4.14.3 postprocess autoexp,strength 4.14.4 postprocess filter3 4.14.5 postprocess filter5 4.14.6 postprocess gblur,blur radius,blend 4.14.7 postprocess mult,(r,g,b) 4.14.8 postprocess desaturate 4.14.9 postprocess gamma,(v) 4.14.10 postprocess erode 4.15 previewsize 4.16 rem comment 4.17 renderinfo info text 4.18 renderinfosize text scale,border size in pixels 4.19 showcornersamples (r,g,b) 4.20 showphstats 4.21 smoothprecachescale ratio 4.22 surface_flags flags 4.23 lwbasenormalgrab 4.24 outputformat pnga; 4.25 gradients_flags 4.26 needbuffers 4.27 lwo2airpolys 4.28 local oversample 4.29 gradients_neighbour 5 Custom GUI plugins

About Commands

Kray has a built in script language for scene definition. It allows user to define the scene in a text file. LightWave's version of Kray uses script to pass parameters from GUI to Kray render core (you can see it if you open .lws file with Kray settings in a text editor). Some Kray options are not exposed in GUI and are available only from Kray script.

You can run Kray script commands from Kray GUI level. On the misc Tab there are 2 fields: Header commands and Tailer commands. They correspond to Kray script commands fired before importing LW scene (Header) and after import (Tailer). Some commands should be fired before importing LW's scene, some after and some works no matter where they are placed.

Header commands

var __blendss

Determines how polygons casts shadows (for direct illumination).

value = 0 - polygon cast shadow no matter if it is front sided or back sided to the light source.

value = 1 - only front side of polygon casts shadow (like in LW).

value = 2 - only back side of polygon casts shadow.

Example:var __blendss,0; // default value

var __undersample_edge

Sets undersampling mode.

value = 1 means edge undersampling (slower, but more accurate).

value = 0 is corner undersampling.

Example:var __undersample_edge,1; // default value

var __overrideflag

Override surface options let's you controll the way object is rendered. To make your life easier use KrayOverride.ls master plugin which can be found in the downloads section of the webpage.

var __overrideflag in header commands. Meaning of bits of flag is below:

1. all surfaces cast shadow 1 (even transparent surfaces will cast shadow)
2. disable textures 2 (will use only base color)
3. disable color 4 (overrides all object with specified color)
4. disable shading 8 (disables all shading and shadows)
5. disable reflection/refraction blur: 16
6. disable luminostiy: 32
7. disable specular: 64
8. disable reflection: 128
9. disable transparency: 256
10. disable translucency: 512
11. diffuse only 1024 (renders objects as pure diffuse with no textures, reflections, transparency etc.)

Example: var __overrideflag,1+2+4+1024; is old surface override behaviour (all diffuse including reflection and refraction)

Example: var __overrideflag,2+16+64; does not use Override surface color, but disables only textures (surface color is used).

Tailer commands

recurse

Sets ray recursion depth and overrides LightWave's setting. Allows to set higher recursion depth then available in LW.

Example: recurse 100;

octree

octree <depth>,<object per octree leaf>;

<depth> - octree depth the same as "Max octree depth in GUI"

<object per octree leaf> - how many objects will octree leaf will include. Default value is 14. Resonable values are 4-50. Higher means slower rendering, but lower octree memory usage

Example: octree 60,20;

octsmallcube

Usage: octsmallcube <ratio>;

<ratio> Additional parameter for octree generation. It is a ratio between size of polygon and smallest octree leaf. For advanced users.

Example: octsmallcube 2;

octbuild

octbuild <cost>,<separation>,<force_split>;

<cost> - parameter that controls how much ram per polygon will be used by octree. Default is 40. Reasonable values are 10 (low memory usage, slower raytracing), 200 (more mem, faster render)

<separation> - another trade of between ram and speed. Default 0.1. Values between 0-1. Resonable values are <0.5

<force_split> - 0 or 1. If zero Kray will not divide scene where it looks that this will not give much (speed). If 1 it will divide it anyway and hopes next division will give some gain.

Example: octbuild 60,0.1,0;

octshow 2

Shows octree. Green boxes means fine division. Yellow not so good, but good enough. Red poor and white bad. If there are some small white or red boxes but most of they are green its ok. If white or red boxes dominates or they are big, this means raytracing performance will be poor.

Example: octshow 2;

Other commands

Commands below can be used in either header or tailer.

about

Displays info about rendering engine.

Example:about;

cam_singleside

If mode = 1 camera rays intersects front side of polygon only. When mode = 0 camera rays intersects both sides of polygon.

Example:cam_singleside 1; // default value

debug "debug_flags"

Displays debug infos in rendering log. debug_flags determines what information will be displayed.

debug_flags	Meaning
0	No debug info
1	Luminosity lights
2	Objects import
4	Rendering finalization
8	Log to file (Default filename is kray_log.txt. It can be changed with logfile)

You can sum debug_flags. For example debug_flags = 2+8 will show object import info and save render log to a file. By default debug_flags is set to 0.

Example: debug 1+2+4+8;

echo "text"

Displays text on Kray console.

Example: echo "This text will be displayed in Kray console.";

include "filename"

Allows to load set of Kray script commands from external file.

Example: include "myfile.txt";

lmimportance "importance"

Controls how accurate direct light and caustics are computed during lightmap building. importance = 1 computes direct light and caustics with best quality (slowest). importance = 0 gives fastest, but most inaccurate result.

Example: lmimportance 0.5;
         lmimportance 0; // default value

logfile "filename"

Enables loging to a file and sets log filename. See debug for more loging options.

Example: logfile 'render_log1.txt';

lwtransoptions sideness_mode,color

sideness_mode determines how transparency/refraction works.

sideness_mode = 0 transparency/refraction ray leaves object before next intersection

sideness_mode = 1 transparency/refraction ray intersects both sides of a polygon

sideness_mode = 2 transparency/refraction ray intersects front hit front side of polygon only

If color = 1 transparency and refraction amount is computed separately for r,g,b components if there is a refraction/transparency texture. color = 0 is LW compatible setting, transparency and refraction uses grayscaled refraction/transparency texture.

Example: lwtransoptions 1,1; // default values

limitdr

Limits dynamic range of primary rays (those fired from camera). If a RGB component of a camera ray is bigger then value it is truncated. This is useful to make sure the overbright parts of an image are antialiased properly, for example the edges of polygons with Luminosity which is much higher than 100%.

By default limitdr is set to zero (no dynamic range limit). Note that for LDR images, image dynamic range is always limited to output exposure. The only difference with limitdr is that this is done per camera ray, not per pixel. Limitdr command can be header or tailer, but it acts different depending on where placed. When its header, limitdr is applied before tone mapping. When its tailer, its applied after tone mapping.

Example:limitdr 0; // no dynamic range limit
        limitdr 1;

mipmap "filter_size_shift,additional_samples,minsamples,maxsamples"

Controls anisotropic filtering of textures (texture antialiasing).

With filter_size_shift you can control texture blurring. Negative values decreases blurring, positive increases. Typical values are between -1 and 1. Values < -1 can cause texture aliasing. Values > 1 can look too blurred.

additional_samples,minsamples and maxsamples controls number of samples Kray uses for anisotropic filtering. More samples - slower rendering, but better quality of texture filtering. Kray computes number of samples from texture anisotropy level and than adds additional_samples to this value. minsamples,maxsamples are minimum and maximum limits.

Example: mipmap 0.2,4,5,30;mipmap 0,0,0,30; // default values

octstats

Displays information about octree used for rays intersection optimization. Information for advanced users and debugging purposes.

Example: octstats;

octsmallcube ratio

Additional parameter for octree generation. It is a ratio between size of polygon and smallest octree leaf. For advanced users.

Example: octsmallcube 2; // default value

photons_singleside

Enables front side intersection only for photons fired from light sources. By default photons hits both sides of polygon.

Example: photons_singleside;

postprocess

Adds post processing filter to Kray's native post processing system.

Note: Some examples are multiline. You can use multiline syntax in Kray script files (see include command), or write a command in single line and directly place in Header/Tailer field.

postprocess add,(r,g,b)

Adds r,g,b values to every pixel of rendered image.

Example: postprocess add,(0.5,0.5,0.5);

postprocess ca,strength,aspect_ratio,distance_influence,samples

Chromatic aberration postprocessing filter.

Strength controls how much the effect is visible.

Aspect_ratio is the pixel aspect ratio.

Distance_influence controls how abberation strength changes with a distance from center of an image.

Samples is numer of samples. Controls quality/speed ratio. Minimum numer of samples is 3 (one sample per r,g,b channel)

Example: postprocess ca,0.1,1,2,100;

postprocess autoexp,strength

Compensates exposure of an image. Strength is a value between 0 and 1. Strength=0 no compensation. Strength=1 full compensation.

Example: postprocess autoexp,1;

postprocess filter3

3x3 convolution filter.

Example 1: postprocess filter3,-1,-1,0,-1,0 ,1,0 ,1 ,1;

Example 2: limitdr 0;postprocess filter3,-1,-1,0,-1,0,1,0,1,1;postprocess add,(0.5,0.5,0.5);

postprocess filter5

5x5 convolution filter.

Example: postprocess filter5,0 ,-1,-1,0 ,0,-1,-1,-1,0 ,0,-1,-1,0 ,1 ,1,0 ,0 ,1 ,1 ,1,0 ,0 ,1 ,1 ,0;

postprocess gblur,blur radius,blend

Gaussian blur blended with original image. Blur radius controls amount of gaussian blurring. Blend is a balance between original image and blurred image. Blend=0 , only original image (filter does nothing). Blend=1 , only blurring, no blending with original. Blend=0.5 , 50% blurred image 50% original image. This filter works nice with overblown areas on the images. See example below and compare it with limitdr examples.

Example: limitdr 0;postprocess gblur,15,0.4;

postprocess mult,(r,g,b)

Multiplies every pixel of the render image by r,g,b values.

Example: postprocess mult,(0.5,0.5,0.5);

postprocess desaturate

v is value between 0 and 1, 0 - no change 1 - grayscale

Example: postprocess desaturate,0.9; will make almost grayscale render.

postprocess gamma,(v)

Example: postprocess gamma,0.8

postprocess erode

This command is good when baking a shadow or any kind of UV. It will expand the borders by so many pixels depending on which value you put in ( 0 to 5)

Example : postprocess erode,5; (in header or tailer commands)

previewsize

Usage: previwesize width,height;

This command enables you to specify the size of render preview window.

Example: previewsize 2000,1500;

rem comment

Comment in Kray script. Not very useful in Header commands and Tailer commands fields, but can be handy in Kray script files (see include).

Example: rem This is comment. Kray will ignore it.

renderinfo info text

Adds information bar to rendered image. Info text can contain following symbols:

Symbol	Meaning
%kray%	Kray logo.
%ver%	Kray version number.
%build%	Kray build time.
%time%	Rendering time in <hours>h <minutes>min <seconds>sec format.
%ptime%	Rendering time in <hours>:<minutes>:<seconds>:<centiseconds> format.
%days%	Render time - days.
%hours%	Render time - hours.
%mins%	Render time - minutes.
%secs%	Render time - seconds.
%centisecs%	Render time - 1/10 seconds.
%sectime%	Total render time in seconds.
%now%	Current time and date.
%file%	Output image filename.
%fileformat%	Output file format.
%width%	Image width.
%height%	Image height.
%fgraysmin%	FG tab/Min rays value.
%fgraysmax%	FG tab/Max rays value.
%threads%	Number of render threads.
%frame%	Current frame.
%buffer%	Buffer name (if rendering buffers other then RGB, see needbuffers).

Example: renderinfo "%kray% %ver% | Rendering time : %time%";

renderinfosize text scale,border size in pixels

Scales render info font size and sets border size.

Example: renderinfosize 0.66,22; // default setting

showcornersamples (r,g,b)

Shows irradiance samples in corners with desired color (those who matches Thin geometry distance). Works only if irradiance caching is on.

Example: showcornersamples (10,0,0);

showphstats

Shows photon statistics.

Example: showphstats;

smoothprecachescale ratio

Sets the ratio between precached and precached filtered search range. Precached filtered interpolates between neighbour irradiance samples and require bigger search range (precached filtered needs at least 2 samples when for precached one sample is enough). High values gives better filtering, but needs more computing power.

Example: smoothprecachescale 1.2; // default value

surface_flags flags

Set flags for diffuse surfaces. Flags allow to enable/disable direct lighting computation and texturing (and output irradiance).

flags	Meaning
1	Enables direct lighting computation
2	Enables textures

Surface flags can be added. flags = 1+2 means that both direct lights and textures must be computed (default setting). Disabling textures and direct lighting is very useful combined with texture baker. This allows to bake irradiance maps in low resolution without loosing details of texturing and shadows.

Example: surface_flags 1+2; // default value

lwbasenormalgrab

In LW9.2-9.5 smoothing normals are computed wrongly. lwbasenormalgrab 1; can be used to overcome this problem.

outputformat pnga;

This will output PNG file with Alpha channel.

gradients_flags

+1 - turns on irradiance gradients (higher quality, but slower interpolation)

+2 - fg samples are computed in rendering phase

+4 - fg samples are computed in antialiasing phase

When +2 or +4 is missing, value from "Precomputed filtered" is used instead of black color.

Example: gradients_flags 0+1+2+4;

needbuffers

Outputs different channels each to a separate file.

+0x1 RGB output (final render) (on by default)

+0x2 alpha channel (filename suffix _alph)

+0x4 texture (suffix _txtr)

+0x8 antialiased z buffer (suffix _zbuf) NOTE: you can save non antialiased z buffer with postprocess savez,'filename.hdr';

+0x10 direct lighting (suffix _dire)

+0x40 indirect lighting (suffix _indi)

+0x100 caustics (suffix _caus)

+0x400 reflections (suffix _refl)

+0x1000 refractions (suffix _refr)

+0x4000 other (suffix _othr) these include backdrop, specularity and everything not included in one of above

Note: You can use outputformat pnga; or outputformat tgaa; tailer commands to force Kray save 32bit (RGBA) PNG or TGA with alpha channel. Otherwise alpha channel will be saved in a separate image.

Example: needbuffers 0+0x1+0x2+0x4+0x8; will output final render, alpha, texture and Z buffer

lwo2airpolys

lwo2airpolys 0;

no need to use air polygons on glass.

lwo2airpolys 1;

99,9% compatible with LW <9.0. Need to use air polys on glass.

local oversample

to enable this type in tailer commands:

prerender <prerender>,<steps>,0;

where prerender overrides prerender from GUI (values from 0 to 1) <steps> - number of prerendering steps (FG refinement steps) additional command controls splotch detection

Example: prerender 1,2,0.01; will render 100% prerender in 2 steps with 0.01 tolerance.

gradients_neighbour

gradients_neighbour <sensitivity>;

values from 0 to 1. default is 0.5

Example: gradients_neighbour 0.01;

Custom GUI plugins

If you are familiar with Lscript or C programming, you may write custom GUI for Kray commands. If you open .lws file with Kray settings in a text editor you can find Kray commands exported from Kray.ls plugin. They are organized in sections. Each section starts with

KrayScriptLWSInlined <section order>;

and ends with

end;

Any plugin that can write settings to .lws file can add new sections and they will be parsed by Kray. Section order is an integer number that tells Kray when this section should be parsed. Sections with lower numbers are parsed first. Sections with negative numbers are parsed before loading LightWave scene (like Header_commands). Sections with positive numbers are parsed after scene is imported to Kray (Tailer commands). Kray.ls uses section numbers -2000 (variables settings) -1000 (header commands) and 1000 (tailer commands).

KrayBuffers is a graphical interface to needbuffers command and example Lscript code of how to write custom GUI plugins for Kray.