jimagereader-wiki/index.md -rw-r--r-- 4.7 KiB
d44f32ccAndrew Adjust indentation to SourceHut style. 2 years ago

JImageReader is a library that can read a few, relatively obscure, image formats in Java, into standard java.awt.Image objects. Its origins are around 2010 or 2011, when my goal was to read PCX images in Java, and I couldn't find a library that had support for that built in. I found writing the image parser to be an interesting problem, and gradually added more images. However, it's very much a hobby project, and a secondary side project; you are welcome to use it in your projects, or to submit a pull request to add support for more formats, but it is not one I frequently update.

Several formats are supported, and many of those have different variants, of which a subset tend to be supported. Support is inherently limited by sample images to verify that these variants can in fact be loaded properly, so particularly if a sub-format that you need it not supported, it may be due to lack of a sample image.

Some formats also support the ImageIO ImageReaderSPI interface. This results in the format being supported when you use ImageIO.read(File fileName) with the library as a dependency.

Supported formats include:

Microsoft Paint (MSP)

The Microsoft Paint format was used in Paint in Windows 1 and Windows 2, and there are two versions of the format. All known variants, including versions 1 and 2, are supported.

Sun Icon (ICO)

The Sun Icon format is an ASCII text image format that is supported on some old Sun workstations, and is not to be confused with modern Windows ICO images (which are not yet supported).

Version 1 of the format is supported, but only for monochrome icons (ed: and apparently some color icons), and only for images that don't include a description.. 8-bit color icons can be viewed, but no guarantee is made as to their color accuracy, as no reference system has been found. No subsequent versions of the format are known.

Bitmap (BMP)

Several versions of the Bitmap (BMP) format are supported. This includes the most common variety - 24-bit RGB Windows 3 bitmaps - but also various other, less common formats.

By file format, supported:

  • Windows 2 and OS/2 1 bitmaps.
  • Windows 3 bitmaps
  • NT 3.1 bitmap
  • Photoshop for Windows NT bitmaps, with an alpha channel
  • OS/2 1.x and 2.x bitmaps (except a few cases listed below)
  • Windows 4 and 5 bitmaps can be opened, but the additional features are not supported.

The following bitmap formats and features are not supported yet:

  • Windows 1 bitmaps
  • Advanced features of Windows 4 and 5 bitmaps
  • OS/2 2.x bitmaps with shorter-than-standard headers
  • OS/2 bitmap arrays, bitmap icons, bitmap color icons, bitmap pointers, and bitmap color pointers
  • 16-bit bitmaps
  • Absolute mode bitmaps
  • Bitmaps with embedded PNGs or JPGs

By compression and bit depth:

  • Unencoded bitmaps are supported in 1, 4, 8, and 24-bit depth
  • RLE encoded bitmaps are partially supported in 8-bit depth (believed to be when width % 4 == 0)
  • Bitfield-encoded bitmaps are supported in 32-bit depth

The following compression/bit depth varieties are not supported:

  • Unencoded bitmaps are not supported in 2, 16, or 32-bit depth
  • 32-bit bitmaps can be read, but alpha content is not preserved
  • RLE encoded bitmaps are not supported in 4-bit depth or sometimes in 8-bit depth (believed to be when width %4 != 0).
  • Huffman encoding (only present on some OS/2 bitmaps)
  • Images with more than 8 bits for one or more of the R, G, B, or alpha components

In addition, if RLE or bitfield encoded images exist in bit depths other than those listed above, they are not supported.

There are a number of unit tests in the test/com/ajtjp/jImageReader folder that verify that the supported formats work, as well as some that are ignored for those formats that are not yet supported (and which will be enabled when they are supported).

Truevision TARGA (TGA)

TARGA version 1 images are largely supported; TARGA version 2 is not currently supported. TARGA 1 variants with support include:

  • 16, 24, and 32-bit Truecolor images, with and without RLE compression (need test image for 16-bit with RLE)
  • 8-bit and 16-bit Grayscale (Black and White) images, with and without RLE compression

These correspond to data types 2, 3, 10, and 11 in the official TGA spec. It is believed that color-mapped TGA 1 images will also work (types 1 and 9), but test images are currently lacking.

Tests for these variants exists in TGATest.java and UnsupportedTGATest.java.


Version 5 PCX files are generally supported, in 24-bit (Truecolor) depth, as well as 256-bit (color-mapped palette) depth.

The following variants are not supported:

  • Versions prior to 5
  • Images whose bytes per line does not equal their width
  • EGA colormapped images
  • Monochrome PCX images