Note: this page is under construction

General

CharLS can be called from C, C++ or languages that can interface with C functions. In the latter case you typically need to rewrite all of interface.h in the terms of the language you use: The function prototypes, the structs, the enums, and annotate the function prototypes as extern. From .net in windows, build the DLL and use IJW to link your VB or C# code to the functions.

Thread Safety

The code in the CharLS library uses no shared mutable state. That means the code is safe to invoke from different threads. If you intend to use CharLS in a multithreaded environment, do check that the c runtime and stl on your platform are thread safe as well, as CharLS uses them. The main thing to watch out for here is that the memory allocator used by stl is thread safe. Internally CharLS does not create threads of its own.

Buffer overruns and security

We live in the 21 century. Computer systems connected to the internet are regularly attacked by people trying to seize control over it. This can be done by crafting data that takes advantage of bugs in the receiving software. CharLS algorithms have been designed to avoid such attacks, and it has unit test to verify this design, but no rigourous review has taken place. if you have examples that cause CharLS to crash on incorrect data, please submit a bug on this website.

Image format

Images are rectangular arrays of pixels. That's easy. If your pixels are in the range 0.255 then that's easy too, that's a byte. For color images, you would expect that everybody would stores 3 colors (Red, Green, Blue) in each pixel, and that everything else stays the same. Well, not neccesarily. Let's take some time to discuss this.
CharLS supports images with samples of 2 to 16 bits per sample. 2-8 bit images are stored in one byte per sample, 9-16 are stored as two bytes (unsigned short in C). the least significant bit is at bit pos 0. CharLS expects the unused bits to be 0, and may fail otherwise. Always. By default, there is no padding at the end of a pixel line. This can be requested by setting the bytesperline property.

For color images, you may know that you can store colors in different formats. By pixel is kind of the default for many platforms and applications. It goes like this:
1 RGBRGBRGBRGB
2 RGBRGBRGBRGB
3 RGBRGBRGBRGB
(this is represents a 4 column, 3 row RGB image. each letter is a color sample. I added image row numbers for comparison with the other formats below)

Compare this with planar:
1 RRRR
2 RRRR
3 RRRR
1 GGGG
2 GGGG
3 GGGG
1 BBBB
2 BBBB
3 BBBB
Here, the first component samples are stored first, then the second, then the third. In JPEG-LS, this is stored as an image with three "scans", a little like three monochrome images after one another.

As it turns out, JPEG-LS supports another flavor, line interleaved. It goes like this:
1 RRRR
1 GGGG
1 BBBB
2 RRRR
2 GGGG
2 BBBB
3 RRRR
3 GGGG
3 BBBB
So here you get the lines in order, but each component separately. You'll be surprised to learn that this is actually the informal default for JPEG-LS color images. It turns out it compresses faster like this. You can also easily do format conversions from this format into the other two, as well as apply color transforms. Because this format is hardly used outside of JPEG-LS, CharLS does not expect you to format your bitmap like this, you should use the by-pixel format when you compress images in by-pixel or line mode, and planar if you ask for planar compression.
On Windows, a GDI bitmap must be padded to an even length in bytes. To accommodate, CharLS supports a bytesperline parameter. Also color ordering is not RGB but BGR. CharLS can do this conversion for you too.

Api Types

JlsParameters

All functions use this structure to communicate the encoder/decoder settings to the application using the library. It must be initialized properly on encode. This struct is always allocated by the calling application, and will provide or receive the parameters used to encode/decode the image.

struct JlsParamaters
{
	int width;
	int height;
	int bitspersample;
	int bytesperline;	// for [source (at encoding)][decoded (at decoding)] pixel image in user buffer
	int components;
	int allowedlossyerror;
	interleavemode ilv;
	int colorTransform;
	bool outputBgr;
	JlsCustomParameters custom;
	JfifParamaters jfif;
};

  • int width: width of the iamge in pixels
  • int height: height of the image in pixels
  • int bitspersample: the number of valid bits per sample to encode. Valid range 2-16. When greater than 8, pixels are assumed to stored as two bytes per sampe, otherwise one byte per sample is assumed.
  • int bytesperline: the stride (line length) in bytes of uncompressed image.
  • int components: number of components (RGB = 3, RGBA = 4, monochrome = 1;
  • int allowedlossyerror: determines how lossy encoding is, high numbers denote higher compression ratio. 0 means lossless compressoin)
  • interleavemode ilv: determines the order of the color components in the compressed stream.
    • ILV_NONE (0) means that Red, Green and Blue are all sent separately as different scans. So for an RGB image, one scan for red, one for green, one for blue. For this mode, the uncompressed data should also be stored like that.
    • ILV_LINE (1) means the compressor encodes one line at a time. So for each line in an image, first all the red samples are sent, then the green, then the blue.
    • ILV_SAMPLE (2) means the compressor encodes a pixel at a time. For each pixel, the red, green and blue are sent immediately after each other. In this mode, CharLS can handle only 3 component images (so no RGBA/CYMK).
ILV_LINE is reccomended for color images. Compression ratios will be similar for each mode, but performance (coding speed) is best for ILV_LINE. For monochrome images, always use ILV_NONE.
  • colortransform: if your input image is RGB, you can specify a lossless color transform. Color transforms improve compression ratios for artificial images or images with a lot of grayscale in them. If a colortransform is used, this is stored in the bitstream. If CharLS comes across such bitstreams it will automatically reverse the color transforms. 0 means no color transform, 1, 2 and 3 are different color transforms, of which 1 is the simplest (reccomended). 3 is similar to the YBR_RCT used in JPEG 2000. This feature was added to CharLS because the orignal HP code supported it and there are JPEG-LS files out there with colortransforms.
  • outputBgr: when set to true, CharLS will reverse the normal RGB output (when decoding) to BGR. Will work when decoding RGB or RGBA images.
  • JlsCustomParameters custom: The JPEG-LS standards allows you to manually fine tune the algorithms default settings for T1-T3 and the RESTART INTERVAL. If you leave all to 0, the JPEG-LS defaults are calculated from the image's bitcount and compression mode.
  • JfifParameters jfif: On decoding, embedded Jfif information (such as physical size) are put in to this struct.
Optional parameters:
  • colorTransform: color transform used in the compressed stream. The color transforms are all lossless and are an HP proprietary extension of the standard. Do not use the color transforms unless you know the receiving understands them. There are 3 color transforms numbered 1-3 (0 means no transform). Color transform typically improve compression ratios only for sythetic images (non-photorealistic computer generated images).
  • outputBgr: only valid when decoding RGB images. If set, CharLS will reverse the order the components to BGR, which is the Windows standard ordering in bitmaps.
  • JlsCustomParameters custom: Here some JPEGLS specific tuning parameters can be set on encoding. Read the JPEG-LS standard before trying. if you leave everything as 0, the default JPEG-LS values will be used.
  • JfifParamaters jfif: pointer to struct that will receive JFIF info when found in the compressed stream (non-standard).

Error codes

enum JLS_ERROR
{
	OK = 0,
	InvalidJlsParameters, 
	ParameterValueNotSupported,
	UncompressedBufferTooSmall,
	CompressedBufferTooSmall,
	InvalidCompressedData,
	ImageTypeNotSupported,
	UnsupportedBitDepthForTransform,
	UnsupportedColorTransform
};


JLS_ERROR enumerates the error codes that can be returned by CharLS. The idea is that there are enough error codes to deduce who is to blame why decoding/encoding is failing. InvalidJlsParameters means that the parameter values are not a valid combination in JPEG-LS, where NotSupported/Unsupported means you have run into a limitation of CharLS. InvalidCompressedData will be returned only if the compressed bitstream is not decodable. This error will also be returned if the bitstream is truncated, or if you provide a non-JPEG-LS bitstream (such as a lossy JPEG image). The remaining two errors denote that you did not allocate enough memory for the output of the encode/decode.

Api functions

Encoding

CHARLS_IMEXPORT JLS_ERROR JpegLsEncode(void* pdataCompressed, size_t cbyteBuffer, size_t* pcbyteWritten, 
	const void* pdataUncompressed, size_t cbyteUncompressed, const JlsParamaters* pparams); 

JpegLsEncode encodes bitmap images to JPEG-LS encoded bitstreams. If this is successful, the function returns 0. Otherwise a JLS_ERROR is returned. When you begin working with CharLS, do look at the return value, it may signal that one input parameter is invalid, or incompatible with another.

Parameters:
  • pdataCompressed: the pointer to the output buffer.
  • cbyteBuffer: the number of bytes in the output buffer. If it is too small this method will fail. In that case, allocate a new buffer of bigger size and retry.
  • pcbyteWritten: here you supply a pointer to an integer value. If encoding was successfull, the number of bytes written is written to this location.
  • pdataUncompressed: a pointer the uncompressed bitmap image to encode.
  • cbyteUncompressed: the number of bytes in the input buffer.
  • pparams: pointer to a struct of type JlsParameters. This struct describes the format of the bitmap to encode, as well as the encoding mode and parameters.
  • info: pointer to a JlsParameters struct. May be null. If it is set, can be used to specify a bytestride (bytes per scanline) or non-standard color ordering. This is mostly useful when decoding directly into platform specific bitmap data structures like windows bitmaps or textures.

Decoding

CHARLS_IMEXPORT JLS_ERROR JpegLsDecode(void* pdataUncompressed, size_t cbyteUncompressed, 
	const void* pdataCompressed, size_t cbyteCompressed, JlsParamaters* info = NULL);

JpegLSDecode decodes JPEG-LS encoded bitstreams to bitmap images. If this is successful, the function returns 0. Otherwise a JLS_ERROR is returned.
Parameters:
  • pdataUncompressed: a pointer to where the data should be decoded. If you decode 16 bit values, this pointer should be aligned on some CPU architectures.
  • cbyteUncompressed: the amount of memory allocated for dempression. If this is less than required for the encoded image, an error is returned.
  • pdataCompressed: the pointer to the input buffer (compressed).
  • cbyteCompressed: the number of bytes in the input buffer
  • info: pointer to a JlsParameters struct. May be null. If it is set, can be used to specify a bytestride (bytes per scanline) or non-standard color ordering. This is mostly useful when decoding directly into platform specific bitmap data structures like windows bitmaps or textures.

Scan Image header

CHARLS_IMEXPORT JLS_ERROR JpegLsReadHeader(const void* pdataUncompressed, size_t cbyteUncompressed, 
	JlsParamaters* pparams);

JpegLsReadHeader reads the header from a JPEG-LS stream without decoding the image. This is useful if you decompress streams of which you do not know the size in advance. Call JpegLsReadHeader first, and deduce from the JlsParameters if you can handle the bitmap, and how much memory you need to allocate to decompress it. Then decode the image with JpegLsDecode.

Encode & compare bitwise against encoded bitstream

CHARLS_IMEXPORT JLS_ERROR JpegLsVerifyEncode(const void* pdataUncompressed, size_t cbyteUncompressed, 
	const void* pdataCompressed, size_t cbyteCompressed);

JpegLsVerifyEncode is a function designed primarily for testing & debugging. In debug builds, CharLS will encode the uncompressed image and verify bit-by-bit that the image is the same as provided in pdataCompressed.

Last edited Sep 24, 2009 at 10:07 PM by jdv, version 18

Comments

No comments yet.