KeyShot 7.0 Scripting Documentation: lux

builtins.object

class RenderOptions(builtins.object)

RenderOptions encapsulates render options in a clear and concise way. The options can be persisted as a dictionary using getDict() and fed to RenderOptions(dict=your_dict) when employing it. The rendering mode can be found by the "render_mode" key of the dictionary. It can have three values: lux.RENDER_MODE_ADVANCED, lux.RENDER_MODE_TIME, or lux.RENDER_MODE_SAMPLES.
Methods defined here:

__eq__(self, value, /): Return self==value.

__ge__(self, value, /): Return self>=value.

__gt__(self, value, /): Return self>value.

__init__(self, /, *args, **kwargs): Initialize self. See help(type(self)) for accurate signature.

__le__(self, value, /): Return self<=value.

__lt__(self, value, /): Return self<value.

__ne__(self, value, /): Return self!=value.

__new__(*args, **kwargs) from builtins.type: Create and return a new object. See help(type) for accurate signature.

__repr__(self, /): Return repr(self).

__str__(self, /): Return str(self).

getDict(...): Get specified options as a dictionary. This can be useful to persist options and then supply to a lux.RenderOptions() constructor when needed to render something. Be wary of the version specified in the dictionary, key values will be converted to the latest version automatically.

setAddToQueue(...): Instead of rendering immediately then it will be added to the internal KeyShot queue, waiting for processing. Note that a copy of the scene will be saved to disk each time. Call lux.processQueue() to process the queue and render what has been added to it. add = Whether to add to queue or not. *

setAdvancedRendering(...): Render in advanced mode with specified samples. samples = The number of samples. *

setAntiAliasing(...): Set anti aliasing level. level = Value from 1 to 8. *

setBackgroundRendering(...): Render in external background process. Note that a background window will open and the call-site will return immediately! ext = Whether to render in background or not. *

setCausticsQuality(...): Set caustics quality. quality = Value from 0 to 10 (0 will disable it). *

setDofQuality(...): Set depth-of-field quality. quality = Value from 1 to 10. *

setGlobalIllumination(...): Set global illumination quality. quality = Quality from 0 to 5 (0 will disable it). *

setGlobalIlluminationCache(...): Set whether or not to use global illumination cache. enable = Use cache. *

setIndirectBounces(...): Set the number of indirect bounces. bounces = The number of indirect bounces. *

setMaxSamplesRendering(...): Render until max samples is reached. samples = Maximum samples. *

setMaxTimeRendering(...): Render the amount of time specified. time = Time in seconds (floating-point number). *

setOutputAlphaChannel(...): Set whether to have alpha channel in output image. enable = Use alpha channel or not. *

setOutputAmbientOcclusionPass(...): Output ambient occlusion pass separate to the result. enable = Output ambient occlusion pass. *

setOutputCausticsPass(...): Output caustics pass separate to the result. enable = Output caustics pass. *

setOutputClownPass(...): Output clown pass separate to the result. enable = Output clown pass. *

setOutputDepthPass(...): Output depth pass separate to the result. enable = Output depth pass. *

setOutputDiffusePass(...): Output diffuse pass separate to the result. enable = Output diffuse pass. *

setOutputDirectLightingPass(...): Output direct lighting pass separate to the result. enable = Output direct lighting pass. *

setOutputIndirectLightingPass(...): Output indirect lighting pass separate to the result. enable = Output indirect lighting pass. *

setOutputNormalsPass(...): Output normals pass separate to the result. enable = Output normals pass. *

setOutputReflectionPass(...): Output reflection pass separate to the result. enable = Output reflection pass. *

setOutputRefractionPass(...): Output refraction pass separate to the result. enable = Output refraction pass. *

setOutputRenderLayers(...): Output render layers separate to the result enable = Output render layers. *

setOutputShadowPass(...): Output shadow pass separate to the result. enable = Output shadow pass. *

setPixelBlur(...): Set pixel blur. blur = Value from 1 to 3. *

setRayBounces(...): Set the number of ray bounces. bounces = The number of ray bounces. *

setRegion(...): Set render region to get subset of image. region = Tuple/list of (start x-axis, start y-axis, end x-axis, end y-axis). Use None to unset a region. *

setSendToNetwork(...): Instead of rendering locally it can be done using KeyShot Network Rendering. send = Whether to send to network or not. *

setShadowQuality(...): Set shadow quality. quality = Value from 1 to 10. *

setSharpShadows(...): Set whether to have sharp shadows or not. enable = Output sharp shadows. *

setSharperTextureFiltering(...): Set whether or not to preserve detail in textures when viewed at grazing angles. enable = Output sharper texture filtering. *

setThreads(...): Set the number of rendering threads. Zero threads means one thread per core. threads = The number of threads. *

Data and other attributes defined here:

__hash__ = None

class SceneNode(builtins.object)

SceneNode encapsulates a node in the scene tree and enables for manipulation, such as hiding/showing, locking/unlocking, setting materials etc., and traversal of the tree. It provides a means for searching and accessing groups, objects and animations for global and local operations. Get an instance of the root of the scene tree using lux.getSceneTree().
Methods defined here:

__eq__(self, value, /): Return self==value.

__ge__(self, value, /): Return self>=value.

__gt__(self, value, /): Return self>value.

__hash__(self, /): Return hash(self).

__init__(self, /, *args, **kwargs): Initialize self. See help(type(self)) for accurate signature.

__le__(self, value, /): Return self<=value.

__lt__(self, value, /): Return self<value.

__ne__(self, value, /): Return self!=value.

__new__(*args, **kwargs) from builtins.type: Create and return a new object. See help(type) for accurate signature.

__repr__(self, /): Return repr(self).

__str__(self, /): Return str(self).

applyTransform(...): Apply a transformation (luxmath.Matrix) to the node and its children. For example, to scale the node to 1/10 of the size: T = luxmath.Matrix().makeIdentity().scale(0.1) node.applyTransform(T) Where 'node' is your lux.SceneNode. Or move an object to absolute position (1, 2, 3): T = luxmath.Matrix().makeIdentity().translate(luxmath.Vector((1, 2, 3))) node.applyTransform(T, absolute = True) trans = The transformation (luxmath.Matrix) to apply. * absolute = Whether to make an absolute transformation instead of a relative one. Must be an object node for absolute transform. (default = False)

centerAndFit(...): Centers and fits the node.

deselect(...): Visually deselects node in the scene.

dump(...): Returns a string representation of the node and its children.

duplicate(...): Duplicate current node and subtree. amount = The amount of duplicates to create (default = 1). linkMats = Whether to link materials or not (default = false).

find(...): Find nodes in the subtree of this node by searching part names and material names. If no names or materials are given then it will find everything. name = Part name to search for (string/tuple/list). mat = Material name to search for (string/tuple/list). all = Match all part names or all material names (default = false). types = Filter results to match types (int/tuple/list) which can be the following the values: lux.NODE_TYPE_GROUP, lux.NODE_TYPE_OBJECT, lux.NODE_TYPE_ANIMATION, lux.NODE_TYPE_MODEL_SET, and lux.NODE_TYPE_MODEL default = all types). depth = The amount of levels to go down the tree. A value of 1 means to only match the direct children of this node etc. (default = -1 = all)

getBoundingBox(...): Get bounding box of node as a tuple of two vectors: min and max. world = Whether to be in world space or not (default = false).

getCenter(...): Get the center of this node. world = Whether to be in world space or not (default = false).

getChildren(...): Get children of group.

getID(...): Get node ID.

getKind(...): Get node kind. Can be one of the following values: lux.NODE_TYPE_GROUP, lux.NODE_TYPE_OBJECT, lux.NODE_TYPE_ANIMATION, lux.NODE_TYPE_MODEL_SET, or lux.NODE_TYPE_MODEL.

getMaterial(...): Get material of a node.

getName(...): Get node name.

getParent(...): Get parent node of this node.

getPath(...): Get path from root to this node as a tuple of lux.SceneNode objects. text = Whether to return the names instead of lux.SceneNode objects (default = false).

hide(...): Hide node.

isAnimation(...): Check if node is an animation.

isDescendantOf(...): Checks if this node is a descendant of the input group node. group = Group node to check sub-tree of. *

isGroup(...): Check if node is a group.

isHidden(...): Check if node is hidden.

isLocked(...): Check if node is locked.

isModel(...): Check if node is a model (direct child of a model set).

isModelSet(...): Check if node is a model set.

isObject(...): Check if node is an object.

isSelected(...): Check if node is selected in the scene.

lock(...): Lock node.

moveToGroup(...): Move this node to another group node. Note: This changes the scene tree. group = Group node to move this node to. *

select(...): Visually selects node in the scene.

setMaterial(...): Set material of a node. If applying to a group then it will apply to all sub nodes. mat = The name of the material to apply. *

show(...): Show node if hidden.

unlock(...): Unlock node.

Functions

applyMaterialMapping(...): Applies a material mapping. dict = Dictionary of object IDs to material names. *

clearBackplateImage(...): Clear the current backplate, if any.

clearGeometry(...): Clears all geometry in the scene. ask = Whether to ask to clear or not (default = false).

dumpTree(...): Dumps the scene tree as a JSON string.

enablePerformanceMode(...): Enable or disable performance rendering mode. enable = Whether to enable or not. (default = true)

encodeVideo(...): Encodes a video from frames of a folder. folder = Folder to encode video frames from. * frameFiles = Name of the frame files. The extension dictates the image format (can be jpg/jpeg, png, exr, or tif/tiff). * videoName = Name of the video file, if any. The extension dictates the video format (can be mp4, mov, avi, or flv). * fps = Frames per second. Relates to the number of frames available! * firstFrame = Frame to start encoding from (defaults to scene settings). lastFrame = Frame to end encoding at (defaults to scene settings). keepFrames = Whether to keep the frames after encoding (default = true) opts = Options specified as a lux.RenderOptions object (see lux.getRenderOptions()).

getAnimationFrame(...): Returns the current animation frame.

getAnimationInfo(...): Returns information about the animation; the duration in seconds, and the amount of frames.

getAnimationTime(...): Returns the current animation time in seconds.

getBackgroundColor(...): Get the current background color as an RGB tuple.

getBackplateImage(...): Get the current backplate, if any.

getCamera(...): Retrieves the currently active camera of the scene.

getCameraDirection(...): Gets the direction of the active camera of the scene.

getCameraDistance(...): Get distance from active camera to pivot/look-at point.

getCameraLookAt(...): Gets the lool-at point of the active camera of the scene.

getCameraPosition(...): Gets the position of the active camera of the scene.

getCameraUp(...): Gets the up vector of the active camera of the scene.

getCameras(...): Retrieves the cameras of the scene.

getEnvironmentImage(...): Get the current environment.

getImportOptions(...): Returns import options in a dictionary: accurate_tessellation: Use alternative tessellation method when available. adjust_camera_look_at: Adjust active camera to look at the imported geometry. adjust_environment: Adjust environment sphere to fit the imported geometry. camera_import: Import cameras if able. center_geometry: Center newly added geometry in the scene. snap_to_ground: Snap newly imported geometry to the ground plane. compute_normals: Compute normals during import, if the format allows. geometry_units: The unit of the imported scene, if not automatically detected. Supply as conversion factor from meters, e.g. cm = 100, feet = 3.2808399, etc. include_nurbs: Include NURBS data. update_mode: If true: Update the active geometry if able. If false: Add the imported model to the root. merge_groups: Apply some post import merging to identically named groups. merge_objects: Apply some post import merging to identically named objects. retain_materials: Apply material changes to the active model to the imported model. separate_materials: Ensure that materials are not linked across parts. separate_parts: Prevent objects from being merged during import. Certain formats only. tessellation_quality: Tessellation quality from 0.0 to 1.0. Higher values should yield more triangles. up_vector: Up vector of the source program. x = 0, y = 1, z = 2, -x = 3, -y = 4, -z = 5 frame: Import a specific animation frame, if able. mayaForceVersion: Maya file import depends on a local Maya installation. This option forces the importer to use a specific version. Should be a string representing the year release, e.g. "2013". group_by: For importers with multiple grouping options. Group by Layer = 0, Group by Shader = 1, Group by Object = 2. ext = File extension to get specific options. getDefaults = Whether to get KeyShot defaults or user settings from a previous import (default = false).

getInputDialog(...): Show dialog according to the arguments provided and return the results. It returns None if cancelled. For example, to show a dialog asking a string, an integer between 10 and 50 that has default value 42, and an item of [1, 2, 3]: values = [("string", lux.DIALOG_TEXT, "Input string:", "hello"), ("int", lux.DIALOG_INTEGER, "Input int:", 42, (10, 50)), (lux.DIALOG_LABEL, "Freestanding label text."), ("item", lux.DIALOG_ITEM, "Select item:", 2, [1, 2, 3])] opts = lux.getInputDialog(title = "This is the title", values = values) The returned options, with default values, would be: {"string": "hello", "int": 42, "item": [1, "2"]} Another trick is using a lambda when clicking "Apply" so the dialog does not need to close every time, and it gets a more interactive feel. values = [("string", lux.DIALOG_TEXT, "Text:", "test")] lux.getInputDialog(title = "Testing Apply", values = values, apply = lambda res: print(res)) In this case it means that whenever "Apply" is clicked the result will be printed to console. title = Title of the dialog. * desc = Description of dialog. (default = None) values = The values of the dialog to build and show. It expects a list of tuples, one tuple for each control. The tuple must contain four or five values depending on the type: key, type, label, and default value, with the additional constraints value in some cases. The key is a string, the label is a string, the type can be one of the following values: lux.DIALOG_TEXT, lux.DIALOG_INTEGER, lux.DIALOG_DOUBLE, lux.DIALOG_ITEM, lux.DIALOG_CHECK, lux.DIALOG_FILE, lux.DIALOG_FOLDER, or lux.DIALOG_LABEL. If the type is lux.DIALOG_INTEGER or lux.DIALOG_DOUBLE then the extra constraints value must be present in the tuple, which is a tuple of minimum and maximum value, and if the type is lux.DIALOG_ITEM then the extra argument must be a list of items to select from. As a special case, if the type is lux.DIALOG_LABEL then the tuple size must be two and the second value must be a string (if the string contains only dashes then it becomes a horizontal divider). * id = Special ID to enable persisting values and when reopening. If given then clicking OK will remember the values so that if the ID is used again then the values will be the default values. Make sure that the ID is unique enough so other scripts won't use it by accident. (default = None) apply = Lambda expression or function to evaluate when "Apply" is clicked in the dialog. It will be invoked with the result dictionary as parameter. The dialog will not close when "Apply" is clicked. (default = None)

getInputDouble(...): Show dialog to input a double. title = Title of the dialog (default = "Enter double"). label = Label of the dialog (default = "Enter double:"). value = Initial value (default = 0). min = Minimum value (default = -2147483647). max = Maximum value (default = 2147483647). decimal = Maximum number of decimal places (default = 1).

getInputFile(...): Show dialog to select file(s) from the file system. multiple = If multiple files can be selected (default = false). title = Title of the dialog (default = "Select file(s)"). folder = The folder to show initially (default = home folder). filter = Filter of files to allow selection from (default = none). An example could be "*.obj *.bip" for all OBJs and BIPs.

getInputFolder(...): Show dialog to select a folder from the file system. title = Title of the dialog (default = "Select folder"). folder = The folder to show initially (default = home folder).

getInputInt(...): Show dialog to input an integer. title = Title of the dialog (default = "Enter integer"). label = Label of the dialog (default = "Enter integer:"). value = Initial value (default = 0). min = Minimum value (default = -2147483647). max = Maximum value (default = 2147483647). step = Stepping amount (default = 1).

getInputItem(...): Show dialog to select an item from a list/tuple of items. items = List/tuple of items to choose from. * title = Title of the dialog (default = "Select item"). label = Label of the dialog (default = "Select item:"). current = Index of initial item (default = 0). editable = If editable or not (default = true).

getInputText(...): Show dialog to input a string. title = Title of the dialog (default = "Enter text"). label = Label of the dialog (default = "Enter text:"). value = Initial value (default = empty string).

getKeyShotVersion(...): Returns the KeyShot version as (major, minor, build, arch) tuple, where arch is either "32 bit" or "64 bit".

getLibraryBackplates(...): Gets all backplates of the library.

getLibraryEnvironments(...): Gets all environments of the library.

getLibraryMaterials(...): Gets all materials of the library.

getLibraryTextures(...): Gets all textures of the library.

getLightingPreset(...): Get currently used lighting preset.

getLightingPresets(...): Get list of lighting presets, both default and custom ones.

getMaterialMapping(...): Gets material mapping: object ID -> material name.

getMaterialTemplates(...): Gets material template names.

getModelSet(...): Returns the active model set.

getOS(...): Returns the OS version string.

getObjectMaterial(...): Gets the material applied to the object(s). obj = Object ID or list of IDs. *

getObjects(...): Gets the object IDs of the scene.

getRenderOptions(...): Returns render options as a lux.RenderOptions object. If defaults is set then it will return the internal defaults, otherwise it's the values as they appear in the render dialog. defaults = Return defaults or not (default = false).

getSceneInfo(...): Returns information about the scene in a dict: name, file name, unit/meter scale and number of triangles, objects, nurbs, curves, and scene width/height.

getSceneMaterials(...): Gets currently used materials of the scene.

getSceneSet(...): (DEPRECATED - REMOVED IN KeyShot 8) Returns the active scene set.

getSceneTree(...): Get lux.SceneNode object representing the root of the scene tree.

getSphericalCamera(...): Get spherical information in degrees of active camera as a list: azimuth, inclination, and twist.

hasContents(...): Determine if there is any content in the scene.

importFile(...): Imports a file. path = File path to import. * showOpts = Show options dialog (default = false). dontAsk = Whether to not ask to save scene first (default = true). opts = Options specified as a dictionary (see lux.getImportOptions()).

isCameraUnsaved(...): Checks if current camera has unsaved changes.

isPaused(...): Checks if renderer is paused.

isPerformanceModeEnabled(...): Checks if performance rendering mode is enabled.

isSceneChanged(...): Checks if scene has been changed.

isUndoEnabled(...): Check whether undo/redo stack is enabled.

newCamera(...): Creates a new camera and makes it active. If not creating unique name and the name exists then it returns false. name = The name of the camera to create. * unique = Whether to create a unique name using numbers at the end (default = false)

newModelSet(...): Create a new model set. name = The name of the new model set to create. * cam = Camera to associate with model set. (default = none)

newScene(...): Clears the scene. dontAsk = Whether to not ask to save scene first (default = true).

newSceneSet(...): (DEPRECATED - REMOVED IN KeyShot 8) Create a new scene set. name = The name of the new scene set to create. * cam = Camera to associate with scene set. (default = none)

openFile(...): Opens or imports a file. path = File path to open. * dontAsk = Whether to not ask to save scene first (default = true).

pause(...): Pauses renderer.

processQueue(...): Process render queue.

removeCamera(...): Removes a camera. name = The name of the camera to remove. *

removeModelSet(...): Remove a model set. If current model set is to be removed then the default model set is chosen. name = The name of the new model set to remove. *

removeSceneSet(...): (DEPRECATED - REMOVED IN KeyShot 8) Remove a scene set. If current scene set is to be removed then the default scene set is chosen. name = The name of the new scene set to remove. *

renderAnimation(...): Renders frames of the scene to a folder and/or video file. folder = Folder to render frames to. * frameFiles = Name of the frame files. The extension dictates the image format (can be jpg/jpeg, png, exr, tif/tiff or psd). (default = "frame.%d.jpg") keepFrames = Whether to keep the frames after rendering (default = true). width = Resolution width in pixels of the frames (default = scene width). height = Resolution height in pixels of the frames (default = scene height). fps = Frames per second (default = 12). videoName = Name of the video file, if any. The extension dictates the video format (can be mp4, mov, avi, or flv). (default = none) opts = Options specified as a lux.RenderOptions object (see lux.getRenderOptions()).

renderFrames(...): Renders frames of the scene to a folder. folder = Folder to render frames to. * frameFiles = Name of the frame files. The extension dictates the image format (can be jpg/jpeg, png, exr, tif/tiff or psd). (default = "frame.%d.jpg") width = Resolution width in pixels of the frames (default = scene width). height = Resolution height in pixels of the frames (default = scene height). fps = Frames per second (default = 12). opts = Options specified as a lux.RenderOptions object (see lux.getRenderOptions()).

renderImage(...): Renders the scene to an image file. path = File path to render to. The extension dictates the image format (can be jpg/jpeg, png, exr, tif/tiff or psd). * width = Resolution width in pixels of the output image (default = scene width). height = Resolution height in pixels of the output image (default = scene height). opts = Options specified as a lux.RenderOptions object (see lux.getRenderOptions()).

renderVR(...): Renders a VR from the scene. folder = Folder to put results in. * name = Name of the VR. * type = VR type. (default = lux.VR_TYPE_TURNTABLE) center = VR center type. (default = lux.VR_CENTER_OBJECT) width = Resolution width in pixels of the frames (default = scene width). height = Resolution height in pixels of the frames (default = scene height). vwidth = Viewport width in pixels. Will be the size that is displayed in VR. (default = resolution width). vheight = Viewport height in pixels. Will be the size that is displayed in VR. (default = resolution height). hframes = Horizontal frames. The VR type plays a role here. (default = 0 = use default) vframes = Vertical frames. The VR type plays a role here. (default = 0 = use default) hbegin = Horizontal angel begin. (only for lux.VR_TYPE_CUSTOM) hend = Horizontal angel end. (only for lux.VR_TYPE_CUSTOM) vbegin = Vertical angel begin. (only for lux.VR_TYPE_CUSTOM) vend = Vertical angel end. (only for lux.VR_TYPE_CUSTOM)

saveCamera(...): Saves current camera if there are unsaved changes.

saveFile(...): Saves scene to a file. If no path is given then known path is used or a dialog will ask. path = File to save to.

screenshot(...): Take a screenshot of current realtime window state and return the path to it.

setAnimationFrame(...): Set the animation frame. frame = The animation frame number. *

setAnimationTime(...): Set the animation time in seconds. secs = The animation time in seconds as a floating-point number. *

setBackgroundColor(...): Applies the RGB color to the background of the scene. color = RGB color tuple. *

setBackplateImage(...): Applies backplate image to the scene. path = Path to the backplate image. *

setCamera(...): Sets the active camera of the scene. camera = The name of the camera to use. *

setCameraDirection(...): Sets the direction of the active camera of the scene. dir = Direction of the camera (x, y, z). *

setCameraDistance(...): Set distance from active camera to pivot/look-at point. dist = The distance. *

setCameraLookAt(...): Set camera to look at an object or a point. obj = Object ID. pt = Point as tuple (x, y, z).

setCameraPosition(...): Sets the position of the active camera of the scene. pos = Position of the camera (x, y, z). *

setCameraUp(...): Sets the up vector of the active camera of the scene. up = Up vector of the camera (x, y, z). *

setEnvironmentImage(...): Applies environment image to the scene. path = Path to the environment image. *

setLightingPreset(...): Set lighting preset to be used. name = Name of preset. *

setMaterialTemplate(...): Applies a material template to part of the scene or all of it if no argument is given. name = Name of the material template. * showSel = Show part selection dialog.

setModelSet(...): Set active model set. name = The name of the new model set to activate. Using 'Default' will set the default model set. *

setObjectMaterial(...): Applies a material to an object in the scene. mat = Material name to apply. * obj = Object ID to apply to. *

setSceneSet(...): (DEPRECATED - REMOVED IN KeyShot 8) Set active scene set. name = The name of the new scene set to activate. Using 'Default' will set the default scene set. *

setSceneUnit(...): Set scene unit and rescale scene if desired. unit = The scene unit can be one of the following values: lux.UNIT_MM, lux.UNIT_CM, lux.UNIT_IN, lux.UNIT_FT, lux.UNIT_M. * keep = Whether to keep current size or rescale (default = True).

setSphericalCamera(...): Set spherical information of active camera: azimuth, inclination, and twist. azimuth = The spherical azimuth in degrees [-180, 180]. * incl = The spherical inclination in degrees [-90, 90]. * twist = The spherical twist degrees [-180, 180]. *

setStandardView(...): Set standard view of currently active camera. view = Standard view to set. Must be one of the following: lux.VIEW_FRONT, lux.VIEW_BACK, lux.VIEW_LEFT, lux.VIEW_RIGHT, lux.VIEW_TOP, lux.VIEW_BOTTOM, lux.VIEW_ISOMETRIC. *

setUndoEnabled(...): Enable or disable the undo/redo stack. When a script context is destroyed then undo is re-enabled if disabled. enable = Enable or not (default = true).

sync(...): Synchronize event queue to enforce pending operations.

unpause(...): Unpauses renderer.