Back Home Table of Contents

NPSD File Format

The NPSD (NPS Image Editor Document) format is a simple, human-readable, backwards-compatible format for storing multilayer images.

Basic Structure

A .npsd file is essentially a .zip file with a specific folder structure. Metadata is generally stored in the NPS INI format, with numerous .ini files placed throughout.

The root of the file MUST contain the following items:

  • a document.ini file
  • a layers folder for holding layer data
  • a resources folder for holding extra data

If any of these are missing, the file is not considered a valid NPSD file and the application MUST abort processing with an error.

document.ini

The document.ini file contains the following sections:

[NPSD]

REQUIRED. Unknown data generates warnings as these options directly control the meaning/structure of the document.

Elements:

  • Signature = $OBSIDIAN$ - REQUIRED to identify this as NPSD. STOP PROCESSING if not present.
  • FormatVersion - Optional. Specifies version of the file format in Major.Minor.Revision format. (This does NOT correlate to the NPS Image Editor version.) If it is missing, assume version 1.0.0.
    • Major - Added some features that break compatibility with old versions of NPS. Display a more critical warning and do not guarantee successful loading.
    • Minor - Added some features that do not meaningfully change the way the document is opened. Continue with warning and load, possibly with limited functionality.
    • Revision - Bug fixes with no changes to functionality. Continue with no warnings.
  • CompatibilityFailMessage - Optional. Displayed as a warning if the file is newer than the application's support.

[Document]

Optional (but probably necessary for the vast majority of documents). Stores document-level information.

Elements:

  • LayerFileFormat - Optional. Suggestion for which format to save layer data in
  • Thumbnail - Optional. Filename of the thumbnail image if there is one. The thumbnail should contain a lower-resolution flattened copy of the image.
  • ActiveLayer - Optional. Index of the active layer

[Meta]

Optional. Stores ancillary data in key-value format. Preserve but don't parse.

[<Any other section>]

Undefined.

Layers Folder

The layers folder contains subfolders in numerically ascending order, starting from 0 for the background layer (see note below). This MUST represent the actual order of layers with 0 being the background layer which also defines canvas size. The background layer is REQUIRED as it defines canvas size. Single-layer documents have only a background layer.

Each folder MUST contain a layer.ini file defining details of that layer.

layer.ini

Each layer.ini file contains the following section:

[Layers]

Required. Unknown data generates warning as these options directly control the meaning/structure of the layer.

Elements:

  • Type - Required. Specifies the type of layer. As of format version 1.0.0 the only valid value is Raster
  • RasterDataFile - Required for Raster layers, Optional as a fallback for others. Specifies a path to a valid raster image file that contains the layer's pixel data.
  • Name - Optional. User-readable title for the layer. If not specified, the sequential number of the layer will be displayed.
  • Location - Required. x,y pair indicating the location of the layer in pixels, relative to the top left corner of the canvas.
  • Visible - Optional. Indicates whether or not the layer is visible. If not visible, it is not part of the image but still appears in the list of layers if your application has one.
  • Locked - Optional. Indicates whether or not the layer is locked for editing. May be ignored by applications that only display (but don't edit) the image.

As of NPSD version 1.2 the following have been added:

  • Opacity - Optional. Specifies the global opacity where 0 is fully transparent and 255 is fully opaque (100%). If omitted, 255 is assumed.
  • BlendingMode - Optional. Specifies the blending mode. The following are valid values: 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. If not specified, "Normal" is assumed. If an invalid value is specified, "Normal" should be used as the fallback and a warning should be displayed.

As of NPSD version 1.3 the following have been added:

  • Outline - Optional. Indicates whether or not the layer should have its shape outlined at all times. Default is False. If set to False, it's still acceptable to outline this layer when certain tools are used such as a layer move tool.
  • ColorMode - Optional. Specifies the color mode which restricts the colors that can be shown. If the renderer supports color modes, it MUST apply the restrictions regardless of what the source data contains, e.g. in Grayscale mode the renderer should convert all input colors to grayscale even if saved as full color. As of NPSD 1.3 the only valid modes are TrueColor or Grayscale but more modes may be added in the future. If not specified, TrueColor is assumed. It is recommended, but not required, to actually save the image data with restricted colors to improve render performance for palettized images in the future.
  • RasterMaskFile - Optional. Specifies a raster image to use as a layer mask. Black regions are fully transparent and white regions are fully opaque, and gray values in between are alpha-blended. The mask MUST have identical dimensions to the layer's image data.
  • MaskEnabled - Optional. Indicates whether or not the mask should be used (allowing it to be disabled temporarily without deleting it). Default is True. This directive has no effect if there is no RasterMaskFile present.

[Meta]

Optional. Stores ancillary data in key-value format. Preserve but don't parse.

NPS Image Editor utilizes the following keys in its operation.

  • Comments - Stores layer-specific comments accessed via the Properties dialog
  • XNPSMaskFromLayer - when using the "mask to layer" feature, this contains the source layer's unique ID

[<Any other section>]

Undefined.

Resources Folder

There is no defined structure for the resources folder. As the spec is updated, e.g. when color management support is added, a specific structure will be defined as part of the official spec. Other applications with their own version of the structure are allowed to define their own formats; however, the official spec MUST take precedence. To ensure that unofficial use of this folder does not clash with future spec updates, prefix any subfolders or files with "x_" since this prefix is guaranteed to not be used in the official spec at any point.

Backwards and Forwards Compatibility

Applications MUST support opening NPSD files with the same major version and older minor version. Applications MAY refuse to open files with a major version that is newer or older.

Forwards Compatibility

Enhancements to the file format will generally allow for basic forwards compatibilty. For example, a new style of layer (like a 3D object) may be added in the future. In this case applications MAY include a raster fallback image for that layer by specifying RasterDataFile and a Type other than Raster; applications that do not understand this type will then be able to load the fallback image and generate a warning. If this is not done, an error image will be used instead.

Any applications that allow editing existing files MUST warn the user if any part of the image was not understood correctly. It is acceptable to allow overwriting the file as long as ample warning is given.

Preservation of Unknown Data

All required elements above MUST be preserved by editors. Metadata MUST be preserved even if the application does not understand it.

Optional elements as well as elements undefined as of the version your application supports MAY be ignored, but as specified above you MUST warn the user about possible loss of data before saving.

Other files and folders MAY be created in the root of the file for additional data storage, but these may not be preserved if an editor does not understand how the data is to be interpreted.