Home You are viewing an offline copy of Help Table of Contents

# NPS Script Reference NPS Image Editor has limited scripting support to help automate certain tasks. Scripts can be run in several ways: Your user script library accessible via the Script menu "Scriptable" extensions whose menus can be placed just about anywhere A single command can be run via Script -> Run Action... (Alt+R) Scripting is currently not complete (but this is a work in progress). Below you can find a reference for the current set of supported commands. ## Syntax The general syntax of a script line is: `command [param1] [param2] [...] set variable=<value>` Parameters and values that consist of strings with multiple words must be quoted. Quotes are optional for single-word strings. `command "hello world" command "hello" command hello set variable="multi word value" set variable="value" set variable=value set variable=multi word value` Lines beginning with # are comments and will not be interpreted. Blank lines will also be ignored. ## Scope Validates the scope of a script. Valid values are: `selection`, `layer`, `document`, and `instance`. A scope of `selection` requires an active selection. `layer` and `document` apply to the active layer and the entire document, respectively. Generally there are no differences here. If a selection is active at the time, it will be placed (and generate the usual undo step). The default scope is `instance` which allows the script to run with virtually no restrictions (but note that all scripts are limited to the currently-running instance even if you use the script to launch a new instance). If the conditions of the scope are not met – for example, if you have a scope of `selection` and no selection is active – the script aborts and the user is prompted to create a selection first. ## Undo steps Calling script commands will perform default behaviors associated with them. For example, placing a selection will cause a "selection placed" action to be added to the undo history. If you are performing multiple actions in a row, they will create individual undo steps which can lead to a sub-optimal user experience. You can group actions with `BeginStep` and `EndStep` to create a single step for the full set of script commands. `BeginStep "Name of step" #Do whatever EndStep` Note that this is not always possible; if the action is already creating multi-undo steps like this, you can't nest them. An error will be displayed if this is not possible. Be sure to call `EndStep` after calling `BeginStep`. If you fail to do this, the script interpreter will do its best to auto-close the step and will display a warning, but this should not be relied upon. For this reason it is also recommended to not open an undo step until after you have performed any conditional logic and only begin a step immediately before the action that will actually modify the image. ## Calling other scripts You can call one script from another using the `ExecScript` command. `#Calls a script in the same folder as the currently-executing one ExecScript "Script.npss" #Calls a script from an external location ExecScript "C:\Users\Me\Documents\My Scripts\External.npss"` ## Command reference The following commands are available. Commands have 0 or more parameters. Parameters are specified after the command with a space. For example: `alert "Hello"`. ### AddLayer Adds a new empty layer to the image ### Alert Displays an alert message. Parameter 1 (required): The message text. Enclose the message in quotes. Parameter 2 (optional): The secondary message text. Enclose the message in quotes. ### ApplyFilter Applies the specified internal filter (same ones used for the Filter Tool) ### ClearBezier Clears the currently-active Bezier curve ### ClearImage Clears the contents of the active layer ### ClearSelection Deletes the active selection without placing it ### CloseDocument Closes the currently-open document ### CloseLayerList Hides the layer list ### Copy Copies the active selection to the clipboard ### CopyActiveLayerToClipboard Copies the image data of the active layer to the clipboard ### CropFit Crops or fits the image. Parameter 1 (required): The crop/fit target. Valid values are: `Selection`, `ActiveLayer`, `AllLayers`, `Canvas` Parameter 2 (required): The crop/fit source mode. Valid values are: `SelectionBounds`, `Content`, `CanvasBoundsCropOnly`, `CanvasBoundsFit`, `AllLayerContent`, `AllLayerBounds` ### CropToContent Crops the selection or image to its content ### CropToSelection Crops the image to the active selection ### Cut Cuts the active selection ### Delete Deletes the active object ### Deselect Removes the active selection. If the selection has moved, this restores the image to the point prior to the selection's placing. ### DragCancel Cancels a file drag operation ### Emit Evaluates the specified value (see: Setting values) ### ExplainTool Outputs a description of the specified tool ### FlattenImage Flattens the image ### FitToCanvas Fits the active layer to the canvas ### InvertSelection Inverts the selection ### LoadSwatches Loads the specified swatch palette ### MergeVisible Merges visible layers ### MoveSelection Moves the selection to the specified location Parameter 1 (required): The selection move type. Valid values are: `Left`, `Right`, `Top`, `Bottom`, `Center`, `CenterHorizontal`, `CenterVertical`, `OriginCanvas`, `OriginLayer`, `OriginViewport` ### NewDocument Creates a new document. Prompts to save the existing one if open. Parameter 1 (optional): The document template. If not specified, the default template is used. Valid templates are: `default` - the default template `prompt` - prompt the user for new document parameters `clipboard` - use the clipboard size `<path to file>` uses the specified .npst or .ini file `x,y,color` – directly specifies the width, height, and background color of the new document ### NewInstance Launches a new NPS Image Editor window. Note that the current script will continue executing in the window it was started from. ### OpenDocument Opens the specified file. Parameter 1 (required): The path to the file to open ### OpenDocumentMRU Opens the specified Most Recently Used file Parameter 1 (required): The path to the file to open ### OpenLayerList Shows the layer list ### Paste Pastes from the clipboard ### PasteAsNewImage Pastes from the clipboard into a new document in the current window ### PlaceBezier Places the active Bezier curve ### PlaceSelection Places the selection ### PromptAction Prompts to run a single script action ### PurgeUndo Clears all undo steps up to this point ### RasterizeText Converts a text ### RefineSelection Refines the selection, only possible when it has not moved and did not come from an external source Parameter 1 (required): The selection refine type. Valid values are: `FillWidth`, `FillHeight`, `Expand`, `Shrink` ### Redo Redoes the last-undone action ### SelectAll Selects all pixels in the active layer ### SelectAllContent Selects all content, excluding empty regions, in the active layer ### SelectionToLayer Converts the selection to a new layer ### Select Creates a selection. This command takes 4 parameters for each of the dimensions (X, Y, Width, Height). Parameters can be specified as absolute pixel values or relative percentage values. ### SelectCopy Creates a selection without removing it from the active layer. Parameters are the same as the `Select` command. ### SetTool Sets the drawing tool ### Sleep Waits for the specified number of milliseconds before continuing. ### Undo Undoes the last action ## UI script commands These are interactive UI actions designed to be launched from custom menus or buttons. ### UiActiveLayerProperties ### UiClipFromScreenshot ### UiClipFromScreenshotPaste ### UiFileNew ### UiFileOpen ### UiFileOpenURL ### UiFormatFont ### UiHelpContents ### UiImageCanvasSize ### UiUmageOffset ### UiImageResize ### UiImageRotateCustom ### UiImageSkew ### UiPasteFromMonitor ### UiPromptText ### UiPaletteEditProperties ### UiRenameActiveLayer ### UiShowConfigFialogSingle ### UiShowReleaseNotes ### UiToggleFullscreen ## Setting values The `set` command sets a value (and performs appropriate logic in response to it). Variables are not case-sensitive. `set forecolor=red` The following values can be set: ### ActiveLayer Sets the active layer given its index (the background layer is 0). ### AirbrushShape Sets the Airbrush tool's shape. Valid values are: `SquareNoise`, `RoundNoise`, `SquareSmooth`, `RoundSmooth` ### BackColor Sets the background or fill color. Color expression is resolved by the Color Resolution Engine. ### BrushShape Sets the Brush tool's shape. Valid values are: `FilledSquare`, `FilledCircle`, `HollowSquare`, `HollowCircle`, `StraightCross`, `DiagonalCross`, `CaligraphyNE`, `CaligraphyNW`, `HorizontalLine`, `VerticalLine` ### BucketFillTransparencyAware Sets the Bucket Fill tool's "transparency aware" setting. Valid values are `true` and `false`. ### ColorCompositingMode Sets the color compositing mode. Valid values are: `Blend`, `Overwrite` ### ColorCyclingMode Sets the color cycling mode. Valid values are: `Pick`, `GradOnce`, `GradLinear`, `GradWave`, `GradVertical`, `Rand`, `Rainbow` ### EyedropperScope Sets the Eyedropper tool's scope. Valid values are: `ActiveLayer`, `AllLayers`, `Screen` ### ForeColor Sets the foreground color. Color expression is resolved by the Color Resolution Engine. ### LineWidth Sets the line width for drawing. ### SelectionCompositingMode Sets the selection compositing mode. Valid values are: `Blend`, `Overwrite` ### TransparencyEditingMode Sets the transparency editing mode. Valid values are: `Opaque`, `Keyed`, `Alpha` ### ZoomLevel Sets the zoom level as a percentage. The percent sign is optional; `120%` is the same as `120`.