# Scripting

## Introduction

OVITO provides a scripting interface that allows users to automate tasks or batch-process a large number of input files. The program's built-in script interpreter is based on the ECMAScript language, which forms also the basis for the popular JavaScript language used in web browsers. If you are not familiar with JavaScript or the ECMAScript language, you can find several tutorials and books online that cover this subject.

OVITO's scripting interface enables programmatic access to various functions of the program such as importing and exporting data, adding modifiers, and rendering images or movies.

## Running scripts

OVITO scripts are normal text files that can be created with any text editor. To execute a script, start OVITO from the command line as follows. Optional arguments are in brackets:

       ovito  [--nogui] --script myscript.js [datafile]

This will run the script file `myscript.js` after program startup. The optional argument `[datafile]` specifies the path or URL of a simulation file to be imported before the script is executed. You can also load an OVITO scene file to restore an old program state including modifiers etc.

The optional `--nogui` option switches to a non-graphical batch mode and OVITO quits after the script has finished executing. In this mode, OVITO's normal user interface is not shown, which is useful when running OVITO scripts on remote machines that don't have a graphics terminal. Note to Windows users: On this platform you won't see any window or console output when using this command line switch. Even though the script is executed in the background, this makes it difficult to tell whether execution was successful or not. On Linux and Mac OS, error messages and text output generated by the script are redirected to the terminal.

## Passing parameters to scripts

The `--exec` command line option allows you to directly pass a script command to OVITO, which will be executed. This is in contrast to the `--script` option, which requires a script file. You can use the `--exec` option to pass command line parameters to a script file as follows:

       ovito --exec "temperature=800" --script myscript.js

In this example, the string `temperature=800` is interpreted as a normal script statement, which sets the value of a variable. This variable can later be accessed from the script program `myscript.js`, which is executed in the same context. To set multiple script variables, you can use `--exec` several times, or simply delimit multiple script statements with semicolons.

You can find more documentation on OVITO's scripting functions in the reference section of this manual.

## Script example

The following example program demonstrates how various functions of OVITO can be accessed from a script:

    // Query program version.
    print("This is Ovito " + ovito.version)

    // Import a data file.
    node = load("../data/NanocrystallinePd.dump.gz")

    // Block execution of the script until the scene is ready, that is, until
    // the input file has been completely loaded.
    // This is an optional step, but it ensures that the modifier we are going to create
    // has access to the input data at the time it is inserted into the modification pipeline.
    // This allows the Color Coding modifier to automatically adjust its interval to the range of
    // values present in the input data.
    wait()

    // Apply a modifier to the dataset.
    node.applyModifier(new ColorCodingModifier({
    	sourceProperty : "Potential Energy",
    	colorGradient  : new ColorCodingHotGradient()
    }))

    // Set up view, looking along the [2,3,-3] vector.
    activeViewport.perspective(Point(-100, -150, 150), Vector(2, 3, -3), 60.0 * Math.PI/180.0)

    // Render a picture of the dataset.
    activeViewport.render({
    	filename    : "rendering.png",
    	imageWidth  : 120,
    	imageHeight : 120
    })

    // Apply two more modifiers to delete some particles.
    node.applyModifier(new SelectExpressionModifier({ expression : "PotentialEnergy < -3.9" }))
    node.applyModifier(new DeleteParticlesModifier())

    // Print the modification pipeline of the selected node to the console.
    print("Current modification pipeline:")
    for(var i = 0; i < node.modifiers.length; i++)
    	print("  " + node.modifiers[i])

    // Perform some analysis.
    cna = new CommonNeighborAnalysisModifier({ cutoff : 3.2, adaptiveMode : false })
    node.applyModifier(cna)

    // Wait until computation has been completed.
    wait()

    // Read out analysis results.
    print("Number of FCC atoms: " + cna.structureCounts[CommonNeighborAnalysisModifier.FCC])

    // Write processed atoms back to an output file.
    save("exporteddata.dump", LAMMPSDumpExporter,
    	{ columnMapping: ["Position.X", "Position.Y", "Position.Z", "Structure Type"] })