Anders
Dahnielson

# Scripting

## Introduction

&k3d; script engine plugins enable you to write scripts to automate tasks or develop simple tools. Available language are JavaScript, while Python and Ruby is work in progress.

The content of this chapter has not yet been updated, why it is not a good representation of &k3d;'s scripting capabilities.

## JavaScript

To indicate that you wish to use the JavaScript Scripting Engine you need to put '//javascript' at the first line of the script. JavaScript is also the default language that tutorials and macros are recorded in. Then, the easiest way to write the skeleton of a script is to use 'Record Macro Script' in the 'Tools' menu and run &k3d; as user: all actions will be recorded and shown in the 'Macro Recorder' window.

A script can be executed in one of three different "contexts":

- global : Application Window > Tools > Play Script

  a script executed in global context is not "associated" with any specific document. In order to work with a specific document, such a script would have to: 1) create a new document 2) open an existing document 3) choose from amongst the current set of open documents, would could be zero-to-many.

- document : Document Window > Tools > Play Script

  a script executed in document context *is* associated with a specific document. In the current JavaScript engine, a script running in document context can access its document as "MyDocument", which is a property of the global object.

- object : Document Window > Hierarchy Tab > Object Context Menu > Play Script

  a script executed in object context is associated with a specific object. In the current JavaScript engine, this object will be accessible as "MyObject", again a property of the global object. Same story as above for other engines. Note: the ultimate purpose for having object context is so we can "embed" scripts in objects and give them scripted behavior.

Here follows a list of available objects:

### File I/O

The JavaScript File I/O objects add rudimentary file I/O capabilities to the JavaScript object model. They are designed to provide a subset of the iostreams capabilities from the C++ standard library:

#### Class: istream

Wraps an input file stream.

##### istream(string Filepath)

Creates a new istream object, opening the given filepath for input.

##### bool istream.eof()

Returns true if the end-of-file flag is set for the stream.

##### string istream.get()

Reads a single character from the stream.

##### string istream.getline()

Reads one line from the stream.

##### string istream.read(integer Count)

Reads a specific number of characters from the stream.

#### Class: ostream

Wraps an output file stream.

##### ostream(string Filepath)

Creates a new ostream object, opening the given filepath for output.

##### ostream.write(string Buffer)

Writes data to the stream.

##### ostream.flush()

Flushes the output stream, forcing writes of any buffered data.

### Class: Application

#### UIClass UI

Returns the (optional) application user-interface object, or null.

#### ScriptEnginesClass Scripts

Returns a ScriptEngines object that can be used to play external scripts

#### string BasePath

Returns the application base path (e.g. /usr/local/k3d).

#### array Documents

The Documents property returns an array containing the set of open Document objects.

#### Document NewDocument()

Creates a new K-3D document.

#### Document OpenDocument( string file )

Opens a K-3D document.

#### bool CloseDocument( DocumentClass document )

Closes an open K-3D document.

#### CommandNodeClass CommandNode()

Return a commandnode.

### Class: UI

#### bool BrowserNavigate( string url )

Displays a URL in the user's preferred web browser.

#### bool Message( string message, string title )

Displays an informational message in a non-modal dialog box.

#### bool ErrorMessage( string message, string title )

Displays an error message in a non-modal dialog box.

#### int QueryMessage( string message, string title, array buttons )

Prompts the user to choose from an array of selections in a modal dialog box.

#### string GetFilePath(string Type, string Prompt, bool PromptOverwrite, string OldPath)

Prompts the user for a filepath, checking for old choices, and storing the current choice for reuse. The following are common arguments to Type, although any string is valid:

- renderfarm

- script

- document

- geometry

- log

- font

- renderframe

### Class: ScriptEngines

#### bool PlayFile( string filepath )

Plays a script stored in the given file. Returns true iff the script is executed successfully.

### Class: CommandNode

#### bool Command( string command, string arguments )

Execute a command on the commandnode.

### Class: Document

#### Application Application

Property return the application that owns document.

#### ObjectCollection Objects

Property returns the collection of K-3D objects within this document.

#### string Path

Property return the filepath to document.

#### bool Import( string file, string format )

Imports a geometry file into the document, using the given file format.

#### bool Export( string file, string format )

Exports the document to a geometry file, using the given file format.

#### bool Save( string file )

Save document to a given file.

#### bool StartChangeSet()

Records an original state that should be restored when undo.

#### bool FinishChangeSet( string string )

Undocumented.

#### bool RedrawAll()

Redraws all cameras.

### Class: ObjectCollection

#### Object Create( string name )

Creates a new K-3D object.

#### array Get()

Return set of objects as an array.

#### Object Object( string name )

Return named K-3D object.

#### bool Delete( string name )

Deletes named K-3D object.

### Class: Camera

#### Document Document

Property return document that owns camera.

#### string SelectionMode

Property to control the selection mode.

#### bool ShowViewport()

Show the camera viewport.

#### bool HideViewport()

Hide the camera viewport.

#### bool Redraw()

Redraw viewport.

#### bool RenderPreview()

Render a preview.

#### bool RenderFrame( string OutImage, bool ViewImage )

Render a single frame.

    maincamera = Document.Objects.Create("Camera");
    maincameraobject = maincamera.Camera;
    maincameraobject.RenderFrame("/tmp/myimage.tiff", true);

#### bool RenderAnimation( string OutImage, bool ViewImages )

Render the animation.

### Class: Object

#### Document Document

Property return document that own object.

#### string Name

Property to set and get object name.

#### array[3] Position

Property to set and get object position. Array has three (3) elements.

#### array[4] Orientation

Property to set and get object orientation. Array has four (4) elements. The first is the angle and the rest XYZ values.

#### array[3] Scale

Property to set and get object scale. Array has three (3) elements.

#### Mesh Mesh

Property return mesh.

#### Camera Camera

Property return camera.

#### bool EditObject()

Called to request that the object open its user interface.

## Python

To indicate that you wish to use the Python Scripting Engine you need to put '#python' at the first line of the script.

The Python implementation of the K-3D API has the same functionallity as the JavaScript one.

    #python

    Application.UI.Message( "I will now open a new document.", "Hello, World!")
    document = Application.NewDocument()
    result = Application.UI.QueryMessage( "Do you wish to keep the document open?", "Question", ["Yes", "No"] )
    if result == 2:
        Application.CloseDocument(document)

To find a complete reference to the whole language please visit http://www.python.org.

### ApplicationClass

#### UIClass UI

Return the UI class.

#### ScriptEnginesClass ScriptEngine

Return the script engines class.

#### list Documents

Return a list of open documents.

#### string BasePath

Return the basepath of the running application.

#### string DialogTemplatesPath

Return the dialogtemplates path.

#### string LibPath

Return the lib path.

#### string ScriptsPath

Return the scripts path.

#### string ShadersPath

Return the shaders path.

#### string SharePath

Return the share path.

#### string TutorialsPath

Return the tutorials path.

#### string OptionsPath

Return the options path.

#### bool Close()

Close K-3D.

#### DocumentClass NewDocument()

Creates a new K-3D document.

#### DocumentClass OpenDocument( string file )

Opens a K-3D document.

#### bool CloseDocument( DocumentClass document )

Closes an open K-3D document.

#### CommandNodeClass CommandNode()

Return a commandnode.

### UIClass

#### bool BrowserNavigate( string url )

Displays a URL in the user's preffered web browser.

#### bool Message( string message, string title )

Displays an informational message in a modal dialog box.

#### int QueryMessage( string message, string title, list buttons )

Prompts the user to choose one of selections in a modal dialog box.

#### bool ErrorMessage( string message, string title )

Displays an error in a modal dialog box.

#### string GetFilePath(string type, string prompt, bool promptoverwrite, string oldpath)

Prompts the user for a filepath, checking for old choices, and storing the current choice for reuse. Valid types:

- renderfarm

- script

- document

- geometry

- log

- font

- renderframe

### ScriptEnginesClass

#### bool PlayFile( string filename )

Execute the script file. Return true on success.

### CommandNodeClass

#### bool Command( string command, string arguments )

Execute a command on the commandnode.

#### CommandNodeClass ChildName, same as : CommandNodeClass GetNode("ChildName")

Return node child (from the Command Node Inspector Tree).

#### value PropertyName, same as : value GetProperty("PropertyName")

Return node property (from the Command Node Inspector Tree).

#### PropertyName = value, same as : SetProperty("PropertyName", value)

Set node property.

#### list Children

Return node children as a string list (from the Command Node Inspector Tree).

#### list Properties

Return node properties as a string list (from the Command Node Inspector Tree).

### DocumentClass

#### ApplicationClass GetApplication()

Return the application that owns document.

#### string GetPath()

Returns the filepath to the document.

#### bool Import( string file, string format )

Imports a geometry file into the document, using the given file format.

#### bool Export( string file, string format )

Exports the document to a geometry file, using the given file format.

#### bool Save( string file )

Save document to a given file.

#### bool StartChangeSet()

Records an original state that should be restored when undo.

#### bool FinishChangeSet( string string )

Undocumented.

#### bool Redraw()

Redraws all cameras.

#### ObjectClass CreateObject( string name )

Create a new K-3D object.

#### list Objects()

Return set of objects as list.

#### ObjectClass GetObject( string name )

Return named K-3D object.

#### bool DeleteObject( string name )

Delete named K-3D object.

### CameraClass

#### DocumentClass GetDocument()

Return document that owns camera.

#### string GetSelectionMode()

Get the selection mode.

#### bool SetSelectionMode( string mode )

Set the selection mode.

#### bool ShowViewport()

Show the camera viewport.

#### bool HideViewport()

Hide the camera viewport.

#### bool Redraw()

Redraw viewport.

#### bool RenderPreview()

Render a preview.

#### bool RenderFrame( string outimage, bool viewimage )

Render a single frame.

#### bool RenderAnimation( string outimage, bool viewimages )

Render the animation.

### ObjectClass

#### DocumentClass GetDocument()

Return document that own object.

#### string GetName()

Get object name.

#### bool SetName( string name )

Set object name.

#### tuple GetPosition()

Get object position. Tuple contain three (3) values.

#### bool SetPosition( tuple vector )

Set object position. Tuple contain three (3) values.

#### tuple GetOrientation()

Get object orientation. Tuple contain four (4) values. The first is the angle and the rest XYZ values.

#### bool SetOrientation( tuple vector )

Set object orientation. Tuple contain four (4) values. The first is the angle and the rest XYZ values.

#### tuple GetScale()

Get object scale. Tuple contain three (3) values.

#### bool SetScale( tuple vector )

Set object scale. Tuple contain three (3) values.

#### MeshClass GetMesh()

Return mesh.

#### CameraClass GetCamera()

Return camera.

#### bool EditObject()

Called to request that the object open its user interface.

### MeshClass

#### list GetPoints()

Return points as a list.

#### list GetPaths()

Return paths as a list.

#### PointClass CreatePoint()

Creates a new point.

#### PathClass CreatePath()

Creates a new path.

### PathClass

#### MeshClass GetMesh()

Return mesh that own path.

#### list GetPoints()

Retrn points in path as a list.

#### bool AddPoint( PointClass point )

Add point to collection.

#### bool RemovePoint( PointClass point )

Remove point from collection.

### PointClass

#### MeshClass Mesh

Get mesh that own point.

#### bool Local = tuple vector

Set local XYZ. Tuple contain three (3) values.

#### tuple Local

Get local XYZ. Tuple contain three (3) values.

#### bool Animated = tuple vector

Set animated XYZ. Tuple contain three (3) values.

#### tuple Animated

Get animated XYZ. Tuple contain three (3) values.

#### bool World = tuple vector

Set world XYZ. Tuple contain three (3) values.

#### tuple World

Get world XYZ. Tuple contain three (3) values.

#### bool Camera = tuple vector

Set camera XYZ. Tuple contain three (3) values.

#### tuple Camera

Get camera XYZ. Tuple contain three (3) values.

#### bool Screen = tuple vector

Set screen XYZ. Tuple contain three (3) values.

#### tuple Screen

Get screen XYZ. Tuple contain three (3) values.

#### bool Normal = tuple vector

Set normal XYZ. Tuple contain three (3) values.

#### tuple Normal

Get normal XYZ. Tuple contain three (3) values.

#### bool Texture = tuple vector

Set texture XYZ. Tuple contain three (3) values.

#### tuple Texture

Get texture XYZ. Tuple contain three (3) values.

#### bool ImplicitTexture = tuple vector

Set implicit texture XYZ. Tuple contain three (3) values.

#### tuple ImplicitTexture

Get implicit texture XYZ. Tuple contain three (3) values.

## Ruby

To indicate that you wish to use the Ruby Scripting Engine you need to put '#ruby' at the first line of the script.

The Ruby implementation of the K-3D API has the same functionallity as the JavaScript one.

    #ruby

    app = ApplicationClass.new()

    app.getUI().message("Welcome to Ruby!","Hello, World!")
    document = app.newDocument()
    result = app.getUI().queryMessage("Do you want to keep the document open?", "Question", ["Yes", "No"])
    if result == 2
    	app.closeDocument(document)
    end

To find a complete reference to the whole language please visit http://www.ruby-lang.org.

### ApplicationClass

#### UIClass UI()

Return the UI class.

#### ScriptEnginesClass ScriptEngine()

Return the script engine class.

#### array Documents()

Return an array of open documents.

#### string BasePath()

Return the running applications base path.

#### string DialgoTemplatesPath()

Return the dialogtemplates path.

#### string LibPath()

Return the lib path.

#### string ScriptsPath()

Return the scripts path.

#### string ShadersPath()

Return the shaders path.

#### string SharePath()

Return the share path.

#### string TutorialsPath()

Return the tutorials path.

#### string OptionsPath()

Return the options path.

#### bool Close()

Close K-3D.

#### DocumentClass NewDocument()

Creates a new K-3D document.

#### DocumentClass OpenDocument( string file )

Opens a K-3D document.

#### bool CloseDocument( DocumentClass document )

Closes an open K-3D document.

#### CommandNodeClass CommandNode()

Return a commandnode.

### UIClass

#### bool BrowserNavigate( string url )

Displays a URL in the user's preffered web browser.

#### bool Message( string message, string title )

Displays an informational message in a modal dialog box.

#### int QueryMessage( string message, string title, list buttons )

Prompts the user to choose one of selections in a modal dialog box.

#### bool ErrorMessage( string message, string title )

Displays an error in a modal dialog box.

#### string GetFilePath(string type, string prompt, bool promptoverwrite, string oldpath)

Prompts the user for a filepath, checking for old choices, and storing the current choice for reuse. Valid types:

- renderfarm

- script

- document

- geometry

- log

- font

- renderframe

### ScriptEnginesClass

#### bool playFile( string filename )

Execute the script file. Return true on success.

### CommandNodeClass

#### bool command( string command, string arguments )

Execute a command on the commandnode.

### DocumentClass

#### ApplicationClass GetApplication()

Return the application that owns document.

#### bool Import( string file, string format )

Imports a geometry file into the document, using the given file format.

#### bool Export( string file, string format )

Exports the document to a geometry file, using the given file format.

#### bool Save( string file )

Save document to a given file.

#### bool StartChangeSet()

Records an original state that should be restored when undo.

#### bool FinishChangeSet( string string )

Undocumented.

#### bool Redraw()

Redraws all cameras.

#### ObjectClass CreateObject( string name )

Creates a new K-3D object.

#### ObjectCollectionClass Objects()

Returns the collection of K-3D objects within this document.

#### ObjectClass GetObject( string name )

Return named K-3D object.

#### bool DeleteObject( string name )

Deletes named K-3D object.

### CameraClass

#### DocumentClass getDocument()

Return document that owns camera.

#### string getSelectionMode()

Get the selection mode.

#### bool setSelectionMode( string mode )

Set the selection mode.

#### bool redraw()

Redraw viewport.

#### bool renderPreview()

Render a preview.

#### bool renderFrame( string outimage, bool viewimage )

Render a single frame.

#### bool renderAnimation( string outimage, bool viewimages )

Render the animation.

### ObjectClass

#### DocumentClass GetDocument()

Return document that own object.

#### string GetName()

Get object name.

#### bool SetName( string name )

Set object name.

#### tuple GetPosition()

Get object position. Tuple contain three (3) values.

#### bool SetPosition( array vector )

Set object position. Array contain three (3) values.

#### array GetOrientation()

Get object orientation. Array contain four (4) values. The first is the angle and the rest XYZ values.

#### bool SetOrientation( array vector )

Set object orientation. Array contain four (4) values. The first is the angle and the rest XYZ values.

#### array GetScale()

Get object scale. Array contain three (3) values.

#### bool SetScale( array vector )

Set object scale. Array contain three (3) values.

#### MeshClass GetMesh()

Return mesh.

#### CameraClass GetCamera()

Return camera.

#### bool EditObject()

Called to request that the object open its user interface.

### MeshClass

#### list GetPoints()

Return points as a list.

#### list GetPaths()

Return paths as a list.

#### PointClass CreatePoint()

Creates a new point.

#### PathClass CreatePath()

Creates a new path.

### PathClass

#### MeshClass GetMesh()

Return mesh that own path.

#### bool AddPoint( PointClass point )

Add point to path.

#### bool RemovePoint( PointClass point )

Remove point from path.

#### PointClass GetPoints()

Get points in path.

### PointClass

#### MeshClass Mesh()

Get mesh that own point.

#### bool Local = array vector

Set local XYZ. Array contain three (3) values.

#### array Local()

Get local XYZ. Array contain three (3) values.

#### bool Animated = array vector

Set animated XYZ. Array contain three (3) values.

#### array Animated()

Get animated XYZ. Array contain three (3) values.

#### bool World = array vector

Set world XYZ. Array contain three (3) values.

#### array World()

Get world XYZ. Array contain three (3) values.

#### bool Camera = array vector

Set camera XYZ. Array contain three (3) values.

#### array Camera()

Get camera XYZ. Array contain three (3) values.

#### bool Screen = array vector

Set screen XYZ. Array contain three (3) values.

#### array Screen()

Get screen XYZ. Array contain three (3) values.

#### bool Normal = array vector

Set normal XYZ. Array contain three (3) values.

#### array Normal()

Get normal XYZ. Array contain three (3) values.

#### bool Texture = array vector

Set texture XYZ. Array contain three (3) values.

#### array Texture()

Get texture XYZ. Array contain three (3) values.

#### bool ImplicitTexture = array vector

Set implicit texture XYZ. Array contain three (3) values.

#### array ImplicitTexture()

Get implicit texture XYZ. Array contain three (3) values.