psp-scan 0.9

Python package for working with Paintshop Pro files

PSP_Scan

This is a library for reading Paintshop Pro files (.pspimage), and converting to BMPs or PNGs. Any PNG files saved, will have a transparency-layer mask stored in the Alpha channel. This enables the PNG files to be used in websites, or in game-development, etc.

You can access the blocks comprising a PSP file, either programmatically, using a Python API, or via command-line arguments, and manipulate or save them to files. They can also be converted to Pillow.Image objects, which lets you use any Pillow function on them, including saving in formats other than BMP/PNG.

Paintshop Pro is a full-featured graphics-editing (raster and vector) program for Windows (only).

Pillow is a Python-package for manipulating graphics (which this library makes use of).

Supported

• Files saved in PSP X format (file-format version 8)

  • this is an older version than the latest commercial software sold, so you need to use File->Save-As

  • (note this is the last release I can find specification-documents for)

• Layers saved in Uncompressed format

  • Use File->Save-As, and select Uncompressed format

  • RLE/LZ77 formats not yet supported, code will raise exception - fixing this is high on my TODO list

• Layers of type Raster/Mask/Group

  • Adjustment-layers, etc, are silently ignored, no exceptions raised

• Two layers maximum in a group (raster + mask) - adding more is also on my TODO list

• PNG files saved, will have a transparency-layer (Alpha channel) grabbed from the PSP file’s Alpha channel.

• CLI (Command-Line Interface), for file manipulation/conversion, individually, or by directory

• API commands for file manipulation/conversion

• Python 2.7

• Tested on Windows 7 (Powershell), should work on later versions

Pip Requirements

• pillow>=3.3.0

• virtualenv (optional, but highly recommended - also virtualenvwrapper)

Installation for Windows

See windows-install for full instructions on installing the program locally.

Note: if you don’t care about virtual environments, installing from PyPi is simple:

pip install psp_scan

If it worked, and your Python site-packages directory is in either PATH or PYTHONPATH, then do:

python -m psp_scan -h

If it didn’t work, then see windows-install for more information about setting paths.

CLI and API

There are two ways you can use the package, either by a command-line interface, or Python API.

The CLI is simpler - you run the psp_scan package, and give it various arguments, such as what file to convert, and to which format, and it performs that action. However, the CLI arguments available are only a subset of the API commands.

The API is more complex - you need to write a Python program that imports the psp_scan package, and write functions that manipulate the Image as wanted, and other functions that save the resulting Image. However, there are more features in the API, which might not be available in the CLI - so if you wanted them, you’d have to use the API. Especially, Pillow functions are available - for instance, you could rotate an image by 90 degrees, or scale it, etc.

CLI Usage

See cli-docs for details

Example of CLI usage and output

Examples

CLI Commands-list

usage: psp_scan.py [-h] [-f {png,bmp}] [-m MASK] [-i DIR] [-o DIR] [-n] [-x] [-l] [-v] [-t] [file_in]

       psp_scan some_file.pspimage            # converts a single file to .png (default)
       psp_scan some_file.pspimage -m 3       # converts a single file to .png, and uses layer 3 mask in Alpha channel
       psp_scan some_file.pspimage -f bmp     # converts a single file to .bmp

       psp_scan -i some_dir -v                # converts all files (recursively) inside directory, prints output
       psp_scan -i some_dir -o new_dir        # converts all files (recursively) to new directory

       psp_scan -l some_file.pspimage         # lists basic block information for file (add -v for more detail)
       psp_scan -x some_file.pspimage         # expands file into blocks/layers, saves to new directory

positional arguments:
  file_in                           single file to convert (optional)

optional arguments:
  -h, --help                        show this help message and exit
  -f {png,bmp}, --format {png,bmp}  format to convert file into (optional, default=png)
  -m MASK, --mask MASK              mask-layer to use for PNG Alpha channel, for single file
  -i DIR, --input-dir DIR           directory to read files from (optional)
  -o DIR, --output-dir DIR          directory to save converted files (optional)
  -n, --non-recursive               read directories non-recursively (default is recursive)
  -x, --expand                      expand file into layers/blocks, save into directory
  -l, --list                        list basic block info (no file conversion) - add -v for more detail
  -v, --verbose                     extra output when processing files

API Usage

See api-docs for details

API Properties-list

- pic.doc
- pic.header            # returns a dict with selected data fields in PSP.info_chunk
- pic.header_full       # returns a dict with all data fields in PSP.info_chunk
- pic.filename          # returns the file used (as a string), or None if a file-pointer was passed in
- pic.width             # width/height for the entire image
- pic.height
- pic.blocks            # returns a list of blocks - the most important block, layers, has its own property
- pic.layers            # returns a list of layers
- pic.as_PIL            # returns a Pillow.Image object using the image's full bitmap (all layers combined)

- pic.layers[0].doc
- pic.layers[0].header  # returns a dict with all data fields in PSP.Layer.info_chunk
- pic.layers[0].name    # returns name of layer
- pic.layers[0].width   # width/height of the visible bitmap-rectangle in the Layer - note this
- pic.layers[0].height  # could be smaller than the image's width/height
- pic.layers[0].rect    # returns the rectangle (or bounding-box) that contains all the visible pixels for this layer
- pic.layers[0].as_PIL  # returns a Pillow.Image object using the layer's bitmap and width/height,
                        # or None if the layer doesn't have a bitmap (like a Group-layer) - check the return
- pic.layers[0].as_XL   # same as .as_PIL, but expands the layer to full image-size

API functions

pic.save_layers_to_file(tmp_dir)  # Saves Raster/Mask layers to separate bitmap files
pic.save_blocks_to_file(tmp_dir)  # Saves everything in all layers (channels, masks, etc) to bitmap files
pic.mask_to_alpha(7)              # returns a Pillow.Image object with an Alpha channel, from the selected mask

Pillow functions

Because the .as_PIL/.as_XL property returns a Pillow.Image object, you can use any of the Pillow functions that work on one. For example:

>>> foo = pic.layers[2].as_PIL
>>> foo.save('layer_three.bmp')
>>> flipped = foo.transpose(Image.ROTATE_90)
>>> flipped.save('layer_three_rot90.bmp')

This includes saving in other formats - for instance:

>>> foo.save('layer_three.tiff', format='tiff')

Additional Random Documentation

• Blocks Overview

• General Code Notes

• Project Origin

Some Credits

Thanks to LeviFiction for helping me with some file-format questions.

psp_scan changelog

0.9 (2016-09-01)

• initial commit (John Crawford)