NPS Script Reference

NPS Image Editor has scripting support to help automate certain tasks. Scripts can be run in several ways:

1. Your user script library accessible via the Script menu
2. The Script Editor
3. "Scriptable" extensions whose menus can be placed just about anywhere
4. 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] [...]
Command param1="value1" param2="value2" [...]
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" "goodbye"
Command hello
Set variable="multi word value"
Set variable="value"
Set variable=value
Set variable=multi word value

Variables start with a $ and will be interpreted in most commands.

Command "$var1 is $var2"
Set variable=$variable2


While not recommended, it is also possible to use the variable form in variable-specific keywords like set.

Set $variable=$variable2


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.

Variables

Variables start with a $ character and can contain letters, numbers, or underscores. Note, however, that commands taking a variable name usually do not need the $ character in front of the variable. For example in the expression Set Var1=$Var2, both Var1 and Var2 are variables, but the $ is only needed when attempting to read from it.

System vs. User variables

System variables are bound to various data in NPS or the document. For example $DrawingTool will set the drawing tool in the current NPS window. Your script can call Set $DrawingTool=Pencil to set the drawing tool to the pencil.

User variables just hold values. Any variable that is not a system variable will be considered a user variable.

Push and Pop

You can push a variable to save off its value for later, then pop it to restore the value. This is primarily useful to maintain consistent user state, e.g. if your script needs to change the drawing tool or foreground color to perform its functionality. Popping a system variable will also update whatever it is bound to.

#You can push just one variable or multiple on the same line
push DrawingTool
push ForeColor MyVariable
pop DrawingTool


Operations

TODO

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".

Abort

Aborts the currently-running script

AddLayer

Adds a new empty layer to the image

AddLayerMask

Adds a new empty layer mask 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.

AnimationNextFrame

Advances the animation forwards by one frame.

AnimationPrevFrame

Advances the animation backwards by one frame.

AnimationPlay

Starts playing the animation asynchronously from the current position.

AnimationPlayOnceAndWait

Plays the animation once from start to finish, waiting until completion to run the next script command.

AnimationPause

Pauses the animation.

AnimationReset

Resets the animation to the beginning.

AnimationGenerateFullFrames

Generates full frames for the animation ("unoptimize").

AnimationSpin

Generates frames to animate the current layer.

Parameter 1 (required): The total number of frames (minimum 2, maximum 360)

Parameter 2 (required): The total duration of the animation

Parameter 3 (required): The background color for areas outside of the frame when it has been rotated

Parameter 4 (required): Interpolation mode

Parameter 5 (required): True for counterclockwise rotation, False for clockwise rotation

ApplyFilter

Applies the specified internal filter (same ones used for the Filter Tool)

BeginDraw

Starts a drawing operation. This is the equivalent of clicking the mouse down.

BeginStep

Begins a multi-undo step which will allow all subsequent commands to be undone as a single operation. Must be closed with EndStep

Parameter 1 (required): The name of the undo step, as it will appear in undo history.

CanvasSize

Sets the canvas size.

ClearBezier

Clears the currently-active Bezier curve

ClearImage

Clears the contents of the active layer

ClearSelection

Deletes the active selection without placing it

ClearStatus

Clears the current status in the status bar

CloseDocument

Closes the currently-open document

CloseLayerList

Hides the layer list

CommitAutosave

Commits auto-save data after an important operation

CommitSettings

Saves the current configuration to the backing store

Copy

Copies the active selection to the clipboard

CopyActiveLayerToClipboard

Copies the image data of the active layer to the clipboard

CopySettingsToAllInstances

Applies the current settings across all running instances

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.

DeleteLayer

Removes the layer from the document

Deselect

Removes the selection without placing it. The actual behavior depends on whether the selection came from the current document or an external source (like the clipboard).

DragCancel

Cancels a file drag operation

Draw

Performs a drawing operation

If only 2 parameters (X and Y) are specified, this acts as the intermediate step between BeginDraw and EndDraw. Think of this as moving the mouse.

If 4 parameters are specified, this performs a complete set of drawing steps – equivalent to clicking the mouse down at X1,Y1 and releasing it at X2,Y2.

DuplicateLayer

Creates a copy of the active layer

Emit

Evaluates the specified value (see: Setting values)

EndDraw

Completes the current drawing operation. This is the equivalent of releasing the mouse.

EndStep

Ends a multi-undo step started with BeginStep

Exit

Exits the program

ExplainTool

Outputs a description of the specified tool

FindNext

Finds the next occurrence of the selected pixels within the image

FitToCanvas

Fits the active layer to the canvas

FlattenImage

Flattens the image

InvertSelection

Inverts the selection

LayerLocked

Locks or unlocks the active layer

LayerVisibility

Toggles visibility of the active layer

LoadSwatches

Loads the specified swatch palette

LoadClassicPalette

Loads a classic color palette (bottom of the screen)

LoadSelection

Creates a selection from the specified file path

LoadSetting

Loads a specific configuration setting.

Log, LogInfo, LogWarning, LogError

Logs the specified text to debug

Parameter 1 (required): The message to output to the log. Enclose in quotes.

MarkClean

Marks the image clean (unmodified)

MarkDirty

Marks the image dirty (modified). This will prompt the user to save when closing.

MaskToLayer

Converts the current layer's mask to an editable layer

MeasureText

Calculates the dimensions of a text string

MergeDown

Merges the active layer with the one below it

MergeVisible

Merges visible layers

MoveObject

Moves the selection, text, or bezier 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

PlaceText

Places the text

PromptAction

Prompts to run a single script action

PromptColor

Prompts to select a color and stores the color expression to a variable

PromptFileOpen

Prompts to open an existing file for loading and stores the path to a variable

PromptFileSave

Prompts to open a new or existing file for saving and stores the path to a variable

PurgeUndo

Clears all undo steps up to this point

RasterizeText

Converts the current text to an image selection, allowing it to be modified like an image

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

Refresh

Refreshes the current image data. Useful for long-running operations to show visible progress.

ReloadSettings

Reapplies current saved settings to the current instance of NPS

RenameActiveLayer

Renames the active layer

Resize

Resizes the active layer

Save

Saves the document interactively

SaveCopy

Saves a copy of the document to the specified path. File format will automatically be determined based on the file extension.

SaveSetting

Saves a specific configuration value

SaveSettings

Saves the settings for the current instance of NPS

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.

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

SelectCopy

Creates a selection without removing it from the active layer. Parameters are the same as the Select command.

SetAllFrameDelay

Sets the frame delay for all frames

Parameter 1 (required): The frame delay, in milliseconds.

SetAllFrameDisposal

Sets the frame disposal method for all frames

Parameter 1 (required): The frame disposal mode, in milliseconds. Valid values are: Default, Combine, Background, Previous

SetCursor

Sets the drawing cursor

SetGlobalColorMode

Sets the global color mode of the image

Parameter 1 (required): True to enable global color mode, False to disable global color mode (each layer has its own color mode).

SetTool

Sets the drawing tool

Sleep

Waits for the specified number of milliseconds before continuing.

Undo

Undoes the last action

UpdateStatus

Updates the status bar during an operation

UI script commands

These are interactive UI actions designed to be launched from custom menus or buttons.

UiActiveLayerProperties

UiAnimationSpin

UiClipFromScreenshot

UiClipFromScreenshotPaste

UiFileNew

UiFileOpen

UiFileOpenURL

UiFileSave

UiFileSaveAs

UiFormatFont

UiHelpContents

UiImageCanvasSize

UiImageGenerateIconVariants

UiUmageOffset

UiImageResize

UiImageRotateCustom

UiImageSkew

UiPaletteEditProperties

UiPasteFromMonitor

UiPromptText

UiRenameActiveLayer

UiSetAllFrameDelay

UiSetAllFrameDisposal

UiSetAnimationSpeed

UiShowConfigDialogSingle

Displays a configuration dialog for a single page

UiShowReleaseNotes

UiToggleFullscreen

Setting system variables

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).

ActiveLayerBlendingMode

Sets the active layer's blending mode.

Valid values are: Normal , Dissolve , Keyed , Multiply , Screen , Overlay , HardLight , SoftLight , HardMix , ColorDodge , ColorBurn , Add , Subtract , Divide , Difference , Exclusion , LightenOnly , DarkenOnly , LighterColor , DarkerColor , BitwiseAND , BitwiseOR , BitwiseXOR , BitwiseXNOR , BitwiseOverIMPBase , BitwiseBaseIMPOver , RGBRed , RGBGreen , RGBBlue , RGBAverage , HSLHue , HSLSaturation , HSLColor , HSLLightness , HSLRollHue , Unknown

ActiveLayerColorMode

Sets the active layer's color mode.

Valid values are: TrueColor , HighColor , WebSafe , Grayscale , Bitmap , Palette , Indexed

ActiveLayerTransparencyMode

Sets the active layer's transparency mode.

Valid values are: AlphaChannel , AlphaBit , TransparentColor , None

ActiveLayerOpacity

Sets the active layer's global opacity. 0 is fully transparent and 255 is fully opaque.

ActiveLayerName

Sets the active layer's name.

AirbrushShape

Sets the Airbrush tool's shape.

Valid values are: SquareNoise , RoundNoise , SquareSmooth , RoundSmooth

AirbrushIntensity

Sets the Airbrush tool's intensity.

AnimationRepeat

Sets the animation repeat mode.

Valid values are: True , False

BrushShape

Sets the Brush tool's shape.

Valid values are: FilledSquare , FilledCircle , HollowSquare , HollowCircle , StraightCross , DiagonalCross , CaligraphyNE , CaligraphyNW , HorizontalLine , VerticalLine

BucketFillMode

Sets how the Bucket Fill tool chooses pixels.

Valid values are: All , Contiguous , Bounded , Inverse

BucketFillDirections

Sets the number of directions the Bucket Fill tool will search in.

Valid values are: 4 , 8

BucketFillTolerance

Sets the tolerance of the Bucket Fill tool. A tolerance of 0 requires colors to match exactly.

BucketFillTransparencyAware

Sets whether or not the Bucket Fill tool is aware of transparent pixels in the image.

Valid values are: True , False

ColorCompositingMode

Sets how colors are blended when drawing with semi-transparent colors.

Valid values are: Blend , Overwrite

ColorCyclingMode

Sets the color cycling mode.

DocumentEnableAnimation

Sets whether the current document supports animation.

Valid values are: True , False

DocumentFrameMode

Sets whether layers should be displayed as independent frames or blended layers.

Valid values are: True , False

DocumentGlobalColorMode

Sets whether all layers use the same color mode (and palette, if applicable).

Valid values are: True , False

DrawingTool

Sets the current drawing tool.

Valid values are: Pointer , Move , RectangularSelect , Hand , FreeformSelect , Zoom , MagicWand , Gradient , Eyedropper , Fill , Pencil , Eraser , Airbrush , FilterTool , Line , Warp , BasicRectangle , RoundedRectangle , Ellipse , Polygon , Text , Bezier , Clone , TextureBrush , Brush , CustomBrush

EyedropperScope

Sets the scope of the Eyedropper tool.

Valid values are: ActiveLayer , AllLayers , Screen

ForeColor

Sets the foreground color to use for drawing.

BackColor

Sets the background color to use for drawing.

LineWidth

Sets the line width (in pixels) to use for drawing.

SelectionCompositingMode

Sets how the selection handles transparent pixels.

Valid values are: Blend , Overwrite

ShapeFillMode

Sets the fill mode for various shape tools.

Valid values are: BorderOnly , BorderFill , FillOnly

Text

Sets the text in the Text tool.

TextAlignment

Sets the alignment of text within the Text tool.

Valid values are: TopLeft , TopCenter , TopRight , MiddleLeft , MiddleCenter , MiddleRight , BottomLeft , BottomCenter , BottomRight

TextBackground

Sets the background of the Text tool.

Valid values are: Transparent , Solid , Rounded , AverageColor , Blur

TextEffect

Sets the text effect for the Text tool.

Valid values are: None , Outline , Shadow , SimpleShadow , Glow , GradientH , GradientV , Sponge

TextFont

Sets the font family used by the Text tool.

TextFontSize

Sets the font size used by the Text tool.

TextFontStyle

Sets the value of TextFontStyle

Valid values are: Bold , Italic , Underline , Strikeout , Bold Italic , Bold Underline , Bold Strikeout , Bold Italic Underline , Bold Italic Strikeout , Italic Underline , Italic Strikeout , Italic Underline Strikeout , Underline Strikeout , Bold Italic Underline Strikeout

TransparencyEditingMode

Sets the behavior of empty regions of the image, such as those exposed by moving a selection or expanding the canvas.

Valid values are: Opaque , Keyed , Alpha

ZoomLevel

Sets the current zoom level.