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 K-3D 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.

<< Previous 
Table of Content
  Next >>