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

As of NPSD version 1.4 the following have been added:

• GlobalColorMode - Optional. If True, there is a single color mode (and palette, if applicable) for the entire document. This information is stored on the background layer. If False, each layer can have its own color mode and palette.
• FrameMode - Optional. If True, the renderer should display each layer individually without blending with the layers below it, as a "self contained" frame or page. If False, layers are blended as a stack. Default value is False.
• SupportsAnimation - Optional. If True, this means that the image supports animation by displaying one frame after another. It is up to the renderer to determine how the layers are displayed for editing. See the AnimationFrameDelay and AnimationFrameDisposal section for details on how the layers will interact with each other.
  
  If False, layers should not be treated as animated.
• SupportsSemitransparentPalette - Optional. If True, the document supports semitransparent colors in palettes. This determines whether drawing tools need to take this into account and e.g. allow specifying a semitransparent color in a palette editor. (Note that even if this is False, you can still use fully-transparent colors in palettes.)
• TransparentBackgroundColor - Optional. Specifies a color to use for transparent regions of the image. This will be used when erasing to transparency with a transparency mode of None, or when saving transparent images to a format that doesn't support it (e.g. JPEG).

[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:

[Layer]

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, so the renderer must handle unknown modes gracefully. If not specified (or unknown), 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.

As of NPSD version 1.4 the following have been added:

• ColorMode - Optional As of NPSD 1.4 the additional valid modes are HighColor, WebSafe, Bitmap, Palette, and Indexed. The Palette and Indexed modes require that a Palette is specified.
  
  The Indexed mode behaves differently from the rest. While other modes restrict the data in the RasterDataFile, the Indexed mode affects how this data is interpreted. Data MUST be saved as grayscale (with alpha channel) and then the rendered must use the palette to colorize the image. While it would be theoretically possible to save a native indexed file as the raster data, no standard formats will support this together with an alpha channel, so the grayscale format was selected.
• Palette - Optional unless ColorMode is set to Palette or Indexed, in which case Required. Specifies the filename of the palette in .npl format.
• TransparencyMode - Optional Specifies how the layer handles transparency. Valid modes are AlphaChannel, AlphaBit, TransparentColor, and None. The TransparentColor mode is only valid if the image has a palette, and the palette must contain a transparent color in order to have any transparent regions. Default is AlphaChannel.
• AnimationFrameDelay - Optional. For animated images only. Specifies the number of milliseconds that the frame is displayed. Default is 0.
• AnimationFrameDisposal - Optional. For animated images only. Specifies the frame's disposal method, i.e. what happens after the frame delay has elapsed. Valid values are Default, Combine, RestoreBackground, and RestorePrevious.

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