From Kraytracing Wiki

Contents 1 About Commands 2 Header commands 2.1 var __blendss 2.2 var __undersample_edge 2.3 var __importflags,__importflags|64; 3 Tailer commands 3.1 animmode 3.2 edgedetectglobals 3.3 edgedetectslot 3.4 octree 3.5 octsmallcube 3.6 octbuild 3.7 octshow 2 3.8 recurse 4 Other commands 4.1 about 4.2 accurateshadows 4.3 cam_singleside 4.4 debug "debug_flags" 4.5 echo "text" 4.6 finishclose 4.7 globalpmblurmultiplier 4.8 importancegammamultiplier 4.9 include "filename" 4.10 lmimportance "importance" 4.11 logfile "filename" 4.12 lwblurdoubleside 4.13 lwo2selfinstance 4.14 lwo2unseenbyrays_affectsgi 4.15 lwtransoptions sideness_mode,color 4.16 lwvolumetrics 4.17 limitdr 4.18 mipmap "filter_size_shift,additional_samples,minsamples,maxsamples" 4.19 octstats 4.20 octsmallcube ratio 4.21 overridesurface 4.22 photons_singleside 4.23 postprocess 4.23.1 postprocess add,(r,g,b) 4.23.2 postprocess ca,strength,aspect_ratio,distance_influence,samples 4.23.3 postprocess autoexp,strength 4.23.4 postprocess filter3 4.23.5 postprocess filter5 4.23.6 postprocess gblur,blur radius,blend 4.23.7 postprocess mult,(r,g,b) 4.23.8 postprocess desaturate 4.23.9 postprocess gamma,(v) 4.23.10 postprocess erode 4.23.11 postprocess saveimage 4.24 previewsize 4.25 rem comment 4.26 renderinfo info text 4.27 renderinfosize text scale,border size in pixels 4.28 showcornersamples (r,g,b) 4.29 showphstats 4.30 smoothprecachescale ratio 4.31 surface_flags flags 4.32 lwbasenormalgrab 4.33 outputformat 4.34 outputtolw 4.35 gradients_flags 4.36 needbuffers 4.37 lwo2airpolys 4.38 lwo2rayslimit 4.39 local oversample 4.40 gradients_neighbour 4.41 Photon received minimum hit ratio 4.42 Z- buffer tonemapper 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 __importflags,__importflags|64;

Controls how shadows are rendered in objects that have dissolve applied. Default is solid shadows. To turn lw compatible mode use:

var __importflags,__importflags|64;

Tailer commands

animmode

Will force Kray to shoot photons across camera path on screamernet by reading frame range from .lws.

 Example:  animmode 1;

edgedetectglobals

edgedetectglobals <edge thickness>,<edges upsampling>;

Controls global (slot independent) settings for edge detector.

edgedetectslot

edgedetectorslot <slot index>,<edge absolute>,<edge relative>,<normal detection>,<z detection>,<overburn level>;

Edge detection settings slot. <slot index>=0 hold default settings for a surface. Slot index used by surface can be controlled in surface options. This allows to use different edge detection settings per surface.

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;

recurse

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

Example: recurse 100;

Other commands

Commands below can be used in either header or tailer.

about

Displays info about rendering engine.

Example: about;

accurateshadows

Control shadow casting routine. Objects with smoothing applied will render smooth shadows even if evaluated polygon is not seen direcly by the light source. In some cases this can produce light leaks (that is the conseqence of "smoothing"). To turn on accurate shadows use accurateshadows 1;. This will prevent leaks, but parts of object in shadow are shadowed and this is percived as "smoothing error"). Default is accurateshadows 1; (LightWave compatible mode).

Example: accurateshadows 1; // Turns on accurate shadows.

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.";

finishclose

Forces Kray windows to close automatically after rendering (useful when you are rendering with LightWaves's Render-Q)

Example: finishclose;

globalpmblurmultiplier

Controls power compensation of blurred reflections/refractions, it should be reverse of photon power multiplier i.e. photon power=5 -> globalpmblurmultiplier 1/5;)

Example: globalpmblurmultiplier 1/5;

importancegammamultiplier

Controls quality of reflection blur. 1 is default. Values >1 - lower quality faster render <1 slower, more rays used in recursive reflections.

Example: importancegammamultiplier 1.5;

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';

lwblurdoubleside

Controls how refraction blur is computed. When set to 1, refraction blur is applied on both incoming and outgoing rays of glass surface. When set to 0 (default, LW compatible setting) refractin blur is applied only for incoming rays.

Example: lwblurdoubleside 1; // enable blur on both sides

lwo2selfinstance

lwo2selfinstance 1; will use old, but faster clip map code (but may cause incompatibility with LW in certain cases when)

lwo2selfinstance 3; will use new clip map code (slower, but more LW compatible)

Example: lwo2selfinstance 3;

lwo2unseenbyrays_affectsgi

lwo2unseenbyrays_affectsgi 0; When you add this to tailer, object can affect gi, but will be unseen by rays (reflection and refraction) and camera. This is not LW compatible, but allows to hide object and still affect GI. By default (LW compatible mode) unseen by rays implies unseen by gi.

Example: lwo2unseenbyrays_affectsgi 0;

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

lwvolumetrics

Enables or disables calculation of FG on volumetrics.

lwvolumetrics 1; Enable rendering of Volumetrics lwvolumetrics 2; Affect FG lwvolumetrics 4; Affect Shadows

Example: lwvolumetrics 1+2+4; // enables FG and shadow calculation on volumetrics.

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

overridesurface

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.

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.)
12. disable lw material node 2048 (turns off material nodes for all surfaces)
13. disable color wireframe mode 4096 (turns off color and replaces with wireframe shader)

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

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

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)

postprocess saveimage

Saves current state of image to a file. Note that used with bitmapprocess allows to save bitmap object to a file.

Example : postprocess saveimage,"filename.png",png;
          bitmapprocess img,saveimage,"test.jpg",jpg,10;  // last param is quality of jpg image

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.
%arch%	System architecture (bus width 32/64 and endianess BE/LE/ME).
%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).

You can also add custom symbols from Kray script level. For example:

var test1,5;
string test2,"test_string";
renderinfo "value is %test1% name is %test2%";

will produce value is 5 name is test_string. The same symbols can be also used in output render filename.

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

This will output file with Alpha channel. You can use the following commands: :outputformat pnga;

outputformat bmpa;

outputformat tifa;

outputformat tgaa;

example: outputformat pnga;

outputtolw

Kray buffers cannot be saved by default when Lightwave image saver is used. To save Kray Buffers and still use Lightwave Image saver do this: set regular Kray output filename and add outputtolw 1; to the list of commands.

example: outputtolw 1;

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 luminosity (suffix _lumi)

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

+0x40000 surface id (suffix _sfid) random color for each surface

+0x100000 object id (suffix _obid) random color for each object

The buffers can be comped together with this formula:

final_image=tone_mapping_operator((caus+dire+indi)*txtr+othr+lumi+refl+refr) 

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.

lwo2rayslimit

It prevents for very deep ray recursion which can be very slow sometimes with LW nodes. This command helps in those situations.

Example: rays above recursion level 1 of node evaluation will be fired only in 90% (0.9) tries.

lwo2rayslimit 1,0.9;

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;

Photon received minimum hit ratio

Limits hit ratio (so sometimes photons will stop firing if the hit ratio is lower). Default value is 1% (0.01).

Example: photonreceivedminhitratio 0.01;

Z- buffer tonemapper

Clips front and back of the Z-buffer to the specified values.

Mode: <linear|inverse|log>

white_clip: Distance of front clipping plane black_clip: Distance of back clipping plane white_value: Color value of front clipping plane black_value: Color of back clipping plane

ztonemapper linear,0,100,1,0;

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 (source code archive) is a graphical interface to needbuffers command and example Lscript code of how to write custom GUI plugins for Kray.