Reference

Table of Contents

Working with jpegs
Manage libjpeg version

Working with jpegs 

Inside DCT domain 

jpeglib.read_dct(path: str) → DCTJPEG

Function for reading of the JPEG DCT coefficients.

The file content is loaded once at the call. Then the operations are independent on the source file.

Reading of DCT is a lossless operation, does not perform the JPEG file decompression.

Parameters: path (str) – Path to a source file in JPEG format.
Returns: DCT JPEG object
Return type: DCTJPEG
Raises: [IOError] – When source file does not exist
Example

>>> jpeg = jpeglib.read_dct("input.jpeg")
>>> jpeg.Y; jpeg.Cb; jpeg.Cr; jpeg.qt

In some cases, libjpeg exits the program. We work on improving this and replace exit with “soft” Python exception.

>>> try:
>>>     jpeg = jpeglib.read_dct("does_not_exist.jpeg")
>>> except IOError: # raised, file does not exist
>>>     pass

After call, only the parameters of JPEG are read, so that it is known, how large buffers need to be allocated. The allocation and reading of the data happens on the first query.

>>> jpeg = jpeglib.read_dct("input.jpeg")
>>>
>>> # at this point, internally jpeg.Y is None
>>> # however on first query, it is read
>>> print(jpeg.Y) # read and returned
>>> print(jpeg.Y) # second time it is already stored in the object
>>> print(jpeg.Cb) # no reading, already stored in the object too

class jpeglib.DCTJPEG(path: str, content: bytes, height: int, width: int, block_dims: ~numpy.ndarray, samp_factor: ~typing.Union[~numpy.ndarray, str], markers: ~typing.List[~jpeglib._marker.Marker], huffmans: ~typing.List[~typing.Dict[str, ~jpeglib._huffman.Huffman]], jpeg_color_space: ~jpeglib._cenum.Colorspace, progressive_mode: bool, num_scans: int, Y: ~numpy.ndarray = <property object>, Cb: ~numpy.ndarray = <property object>, Cr: ~numpy.ndarray = <property object>, K: ~numpy.ndarray = <property object>, qt: ~numpy.ndarray = <property object>, quant_tbl_no: ~numpy.ndarray = <property object>)

JPEG instance to work with DCT domain.

property Cb: ndarray: chrominance blue-difference tensor with shape [num_vertical_blocks, num_horizontal_blocks, vertical_block_size, horizontal_block_size]

property Cr: ndarray: chrominance red-difference tensor with shape [num_vertical_blocks, num_horizontal_blocks, vertical_block_size, horizontal_block_size]

property Y: ndarray: luminance tensor with shape [num_vertical_blocks, num_horizontal_blocks, vertical_block_size, horizontal_block_size]

content: bytes: cached binary content of the jpeg

get_component_qt(idx: int) → ndarray

Getter of the quantization table of a component, dependent on assignment.

Parameters: idx (int) – Component index.
Returns: quantization table of the component
Return type: np.ndarray
Examples

To retreive a component quantization table, simply type

>>> jpeg = jpeglib.read_dct("input.jpeg")
>>> # retrieval of component QTs
>>> qtY = jpeg.get_component_qt(0)
>>> qtCb = jpeg.get_component_qt(1)
>>> qtCr = jpeg.get_component_qt(2)

Usual assignment is Y having qt[0] and Cb and Cr sharing qt[1]. However it may differ.

>>> # retrieval of QTs at index
>>> qt0 = jpeg.qt[0] # usually qtY
>>> qt1 = jpeg.qt[1] # usually qtCb, qtCr (shared)

E.g. ffmpeg uses a single quantization matrix for all three channels.

property has_chrominance: bool

Indicator of presence of color channels.

Returns: True for color image, False for grayscale image
Return type: bool
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.has_chrominance # -> True

>>> im = jpeglib.read_spatial("input.jpeg", "JCS_GRAYSCALE")
>>> im.has_chrominance # -> False

height: int: image height

height_in_blocks(component: int) → int

Getter of height in blocks.

Parameters: component (int) – chroma component index (0 Y, 1 Cb, 2 Cr)
Returns: chroma component height
Return type: int
Raises: [IndexError] – when component index is out of range, dependent on number of components
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.height_in_blocks(0) # -> math.ceil(im.height/8)

Block dimension takes into account the chroma sampling factor for chrominance channels.

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.height_in_blocks(1)
>>> #=math.ceil(im.height/8*im.samp_factor[1, 0]/im.samp_factor[0, 0])
>>> im.height_in_blocks(2)
>>> #=math.ceil(im.height/8*im.samp_factor[2, 0]/im.samp_factor[0, 0])

Block dimensions are not initialized, when constructing from spatial domain.

>>> spatial = np.random.randint(0,255,(32,32,1),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.height_in_blocks(0) # -> None

property num_components: int

Getter of number of color components in the JPEG.

Returns: Number of color components.
Return type: bool
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.has_chrominance # -> 3

>>> im = jpeglib.read_spatial("input.jpeg", "JCS_GRAYSCALE")
>>> im.has_chrominance # -> 1

property num_markers: int

Getter of number of markers.

Returns: Number of markers.
Return type: int
Example

>>> im = jpeglib.read_spatial("input_2markers.jpeg")
>>> im.num_markers # -> 2

Synthetic JPEG has no markers in it.

>>> spatial = np.random.randint(0,255,(16,16,3),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.num_markers # -> 0

path: str: path to the jpeg file

progressive_mode: bool: indicator of progressive (True) or sequential (False) JPEG

property qt: ndarray: quantization tensor with shape [vertical_block_size, horizontal_block_size]

property quant_tbl_no: List: assignment of quantization tables to components, (0 Y, 1 Cb, 1Cr) by default

samp_factor: Union[np.ndarray, str]: sampling factor; first is the channel, (0 Y, 1 Cb, 2 Cr), second is orientation (0 vertical, 1 horizontal) can be also specified as str in format ‘J:a:b’

width: int: image width

width_in_blocks(component: int) → int

Getter of width in blocks.

Parameters: component (int) – chroma component index (0 Y, 1 Cb, 2 Cr)
Returns: chroma component width
Return type: int
Raises: [IndexError] – when component index is out of range, dependent on number of components
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.width_in_blocks(0)
>>> #=math.ceil(im.width/8)

Block dimension takes into account the chroma sampling factor for chrominance channels.

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.width_in_blocks(1)
>>> #=math.ceil(im.width/8*im.samp_factor[1, 1]/im.samp_factor[0, 1])
>>> im.width_in_blocks(2)
>>> #=math.ceil(im.width/8*im.samp_factor[2, 1]/im.samp_factor[0, 1])

Block dimensions are not initialized, when constructing from spatial domain.

>>> spatial = np.random.randint(0,255,(32,32,1),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.height_in_blocks(0)
>>> #=None

write_dct(path: str = None, quality: int = -1, flags: List[str] = [])

Function to write DCT coefficients to JPEG file.

Does not perform JPEG compression, writing DCT is lossless.

Parameters

path (str, optional) – Destination file name. If not given, source file is overwritten.
quality (int, optional) – Compression quality, between 0 and 100. Special value -1 stands for using qt inside the instance or keeping libjpeg default.
flags (list, optional) – Bool compression parameters as str. If not given, using the libjpeg default. More at glossary.

Example

>>> jpeg = jpeglib.read_spatial("input.jpeg")
>>> jpeg.write_spatial("output.jpeg", quality=92)

jpeglib.from_dct(Y: ndarray, Cb: ndarray = None, Cr: ndarray = None, K: ndarray = None, qt: ndarray = None, quant_tbl_no: list = None) → DCTJPEG

A factory of DCTJPEG from DCT data.

The color space inference is based on number of color channels. If chrominance is not given, grayscale JPEG is assumed. For three channels, YCbCr JPEG is assumed.

The quantization table assigment is infered based on components and number of quantization tables given. If you wish a custom assignment, use DCTJPEG.qt.

Warning

Parameter DCTJPEG.path is not initialized. When calling DCTJPEG.write_dct(), you have to specify path, otherwise an error is raised.

Parameters

Y (np.ndarray) – Luminance tensor.
Cb (np.ndarray) – Blue chrominance tensor.
Cr (np.ndarray) – Red chrominance tensor.
K (np.ndarray) – Black tensor.
qt (np.ndarray) – Quantization table tensor.

Example

>>> Y = np.random.randint(-127, 127,(2,2,8,8),dtype=np.int16)
>>> Cb = np.random.randint(-127, 127,(1,1,8,8),dtype=np.int16)
>>> Cr = np.random.randint(-127, 127,(1,1,8,8),dtype=np.int16)
>>> im = jpeglib.from_dct(Y, Cb, Cr, qt=75) # chrominance -> YCbCr infered

When data has one color channels, grayscale is infered

>>> Y = np.random.randint(-127, 127,(2,2,8,8),dtype=np.int16)
>>> im = jpeglib.from_dct(Y) # chrominance -> YCbCr infered

For other color channels, color space can’t be infered. Error is raised.

>>> Y = np.random.randint(-127, 127,(2,2,8,8),dtype=np.int16)
>>> X = np.random.randint(-127, 127,(1,1,8,8),dtype=np.int16)
>>> try:
>>>     im = jpeglib.from_dct(Y, X)
>>> except IOError:
>>>     raised

When output is not specified when writing, error is raised.

>>> Y = np.random.randint(-127, 127,(2,2,8,8),dtype=np.int16)
>>> im = jpeglib.from_dct(Y)
>>> try:
>>>     im.write_dct()
>>> except IOError:
>>>     pass

Inside spatial domain 

jpeglib.read_spatial(path: str, out_color_space: Colorspace = None, dct_method: DCTMethod = None, dither_mode: Dithermode = None, buffered: bool = False, flags: list = None) → Union[SpatialJPEG, ProgressiveJPEG]

Function for decompressing the JPEG as a pixel data (spatial domain).

The file content is loaded once at the call. Then the operations are independent on the source file.

In some cases, libjpeg exits the program. We work on improving this and replace exit with “soft” Python exception.

Parameters

path (str) – Path to a source file in JPEG format.
out_color_space (Colorspace) – Output color space. If not given, using the libjpeg default.
dct_method (DCTMethod) – DCT method. If not given, using the libjpeg default.
dither_mode (Dithermode) – Dither mode. If not given, using the libjpeg default.
buffered (bool) – Read scan by scan. This will return ProgressiveJPEG object.
flags (list, optional) –
Bool decompression parameters as str. If not given, using the libjpeg default. Read more at glossary.

Returns

JPEG object

Return type

SpatialJPEG or ProgressiveJPEG

Raises

[IOError] – When source file does not exist

Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.spatial

>>> try:
>>>     im = jpeglib.read_spatial("does_not_exist.jpeg")
>>> except IOError: # raised, file does not exist
>>>     pass

After call, only the parameters of JPEG are read, so that it is known, how large buffer needs to be allocated. The allocation and reading of the data happens on the first query.

>>> im = jpeglib.read_spatial("input.jpeg")
>>> # at this point, internally jpeg.spatial is None
>>> # however on first query, it is read
>>> print(im.spatial) # read and returned
>>> print(im.spatial) # second time it is already stored in the object

Read progressive JPEG with

>>> im = jpeglib.read_spatial("input.jpeg", buffered=True)

jpeglib.from_spatial(spatial: ndarray, in_color_space: Colorspace = None, scans: List[Scan] = None) → Union[SpatialJPEG, ProgressiveJPEG]

A factory of SpatialJPEG from pixel data.

The color space inference is based on number of color channels. For single channel, grayscale is assumed. For three channels, rgb is assumed.

Warning

Parameter SpatialJPEG.path is not initialized. When calling SpatialJPEG.write_spatial(), you have to specify path, otherwise an error is raised.

Parameters

spatial (np.ndarray) – Spatial representation.
in_color_space (str | Colorspace, optional) – Color space of the input. If not given, infered from the shape.

Raises

[IOError] – When color space can’t be infered.
[TypeError] – When spatial has wrong dtype.

Example

When data has three color channels (in the dimension 2), rgb is infered.

>>> spatial = np.random.randint(0,255,(16,16,3),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial) # 3 channels -> rgb infered
>>> print(im.color_space) # -> Colorspace.JCS_RGB
>>> im.write_spatial("output.jpeg")

When data has one color channels, grayscale is infered

>>> spatial = np.random.randint(0,255,(16,16,1),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial) # 1 channel -> grayscale infered
>>> print(im.color_space) # -> Colorspace.JCS_GRAYSCALE
>>> im.write_spatial("output.jpeg")

For other color channels, color space can’t be infered. Error is raised.

>>> spatial = np.random.randint(0,255,(16,16,7),dtype=np.uint8)
>>> try:
>>>     im = jpeglib.from_spatial(spatial)
>>> except IOError:
>>>     pass

When spatial has a wrong dtype, TypeError is raised.

>>> spatial = np.random.randint(0,255,(16,16,7),dtype=np.uint32)
>>> try:
>>>     im = jpeglib.from_spatial(spatial)
>>> except TypeError:
>>>     pass

When output is not specified when writing, error is raised.

>>> spatial = np.random.randint(0,255,(16,16,3),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> try:
>>>     im.write_spatial()
>>> except IOError:
>>>     pass

class jpeglib.SpatialJPEG(path: str, content: bytes, height: int, width: int, block_dims: ~numpy.ndarray, samp_factor: ~typing.Union[~numpy.ndarray, str], markers: ~typing.List[~jpeglib._marker.Marker], huffmans: ~typing.List[~typing.Dict[str, ~jpeglib._huffman.Huffman]], jpeg_color_space: ~jpeglib._cenum.Colorspace, progressive_mode: bool, num_scans: int, spatial: ~numpy.ndarray = <property object>, color_space: ~jpeglib._cenum.Colorspace = <property object>)

JPEG instance to work in spatial domain.

property color_space: ndarray: color space of the pixel data

content: bytes: cached binary content of the jpeg

property has_chrominance: bool

Indicator of presence of color channels.

Returns: True for color image, False for grayscale image
Return type: bool
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.has_chrominance # -> True

>>> im = jpeglib.read_spatial("input.jpeg", "JCS_GRAYSCALE")
>>> im.has_chrominance # -> False

height: int: image height

height_in_blocks(component: int) → int

Getter of height in blocks.

Parameters: component (int) – chroma component index (0 Y, 1 Cb, 2 Cr)
Returns: chroma component height
Return type: int
Raises: [IndexError] – when component index is out of range, dependent on number of components
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.height_in_blocks(0) # -> math.ceil(im.height/8)

Block dimension takes into account the chroma sampling factor for chrominance channels.

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.height_in_blocks(1)
>>> #=math.ceil(im.height/8*im.samp_factor[1, 0]/im.samp_factor[0, 0])
>>> im.height_in_blocks(2)
>>> #=math.ceil(im.height/8*im.samp_factor[2, 0]/im.samp_factor[0, 0])

Block dimensions are not initialized, when constructing from spatial domain.

>>> spatial = np.random.randint(0,255,(32,32,1),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.height_in_blocks(0) # -> None

property num_components: int

Getter of number of color components in the JPEG.

Returns: Number of color components.
Return type: bool
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.has_chrominance # -> 3

>>> im = jpeglib.read_spatial("input.jpeg", "JCS_GRAYSCALE")
>>> im.has_chrominance # -> 1

property num_markers: int

Getter of number of markers.

Returns: Number of markers.
Return type: int
Example

>>> im = jpeglib.read_spatial("input_2markers.jpeg")
>>> im.num_markers # -> 2

Synthetic JPEG has no markers in it.

>>> spatial = np.random.randint(0,255,(16,16,3),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.num_markers # -> 0

path: str: path to the jpeg file

progressive_mode: bool: indicator of progressive (True) or sequential (False) JPEG

samp_factor: Union[np.ndarray, str]: sampling factor; first is the channel, (0 Y, 1 Cb, 2 Cr), second is orientation (0 vertical, 1 horizontal) can be also specified as str in format ‘J:a:b’

property spatial: ndarray: pixel data tensor

width: int: image width

width_in_blocks(component: int) → int

Getter of width in blocks.

Parameters: component (int) – chroma component index (0 Y, 1 Cb, 2 Cr)
Returns: chroma component width
Return type: int
Raises: [IndexError] – when component index is out of range, dependent on number of components
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.width_in_blocks(0)
>>> #=math.ceil(im.width/8)

Block dimension takes into account the chroma sampling factor for chrominance channels.

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.width_in_blocks(1)
>>> #=math.ceil(im.width/8*im.samp_factor[1, 1]/im.samp_factor[0, 1])
>>> im.width_in_blocks(2)
>>> #=math.ceil(im.width/8*im.samp_factor[2, 1]/im.samp_factor[0, 1])

Block dimensions are not initialized, when constructing from spatial domain.

>>> spatial = np.random.randint(0,255,(32,32,1),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.height_in_blocks(0)
>>> #=None

write_spatial(path: str = None, qt: Union[int, ndarray] = None, quant_tbl_no: ndarray = None, base_quant_tbl_idx: int = None, dct_method: DCTMethod = None, smoothing_factor: int = None, dst_unquantized: str = None, flags: List[str] = [])

Writes a spatial image representation (i.e. RGB) to a file.

Parameters

path (str, optional) – Destination file name. If not given, source file is overwritten.
qt (int | numpy.ndarray, optional) – Compression quality, can be integer 0-100 or a tensor with quantization tables. Defaultly -1 (default factor kept).
quant_tbl_no (numpy.ndarray, optional) – assignment of quantization tables to components, (0 Y, 1 Cb, 1 Cr) by default
base_quant_tbl_idx (int, optional) – base QT to scale, only supported in MozJPEG 3+
dct_method (str | _dctmethod.DCTMethod, optional) – DCT method, must be accepted by _dctmethod.DCTMethod. If not given, using the libjpeg default.
smoothing_factor (int, optional) – Smoothing factor, between 0 and 100. Using default from libjpeg by default.
flags (list, optional) –
Bool compression parameters as str. If not given, using the libjpeg default. More at glossary.

Example

>>> jpeg = jpeglib.read_spatial("input.jpeg")
>>> jpeg.write_spatial("output.jpeg", qt=75)

Grayscale JPEG (only lumo channel) using libjpeg color conversion

>>> x = np.random.randint(0,255,(16,16,3),dtype=np.uint8)
>>> im = jpeglib.from_spatial(x)
>>> im.jpeg_color_space = jpeglib.JCS_GRAYSCALE
>>> im.write_spatial("hello.jpeg")

Going progressive 

class jpeglib.ProgressiveJPEG(path: str, content: bytes, height: int, width: int, block_dims: ~numpy.ndarray, samp_factor: ~typing.Union[~numpy.ndarray, str], markers: ~typing.List[~jpeglib._marker.Marker], huffmans: ~typing.List[~typing.Dict[str, ~jpeglib._huffman.Huffman]], jpeg_color_space: ~jpeglib._cenum.Colorspace, progressive_mode: bool, num_scans: int, spatial: ~typing.List[~numpy.ndarray] = <property object>, color_space: ~jpeglib._cenum.Colorspace = <property object>, qt: ~typing.List[~numpy.ndarray] = <property object>, quant_tbl_no: ~typing.List[~typing.List[int]] = <property object>, scans: ~typing.List[~jpeglib._scan.Scan] = <property object>)

JPEG instance to work with progressive JPEG in spatial domain.

property color_space: ndarray

content: bytes: cached binary content of the jpeg

property has_chrominance: bool

Indicator of presence of color channels.

Returns: True for color image, False for grayscale image
Return type: bool
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.has_chrominance # -> True

>>> im = jpeglib.read_spatial("input.jpeg", "JCS_GRAYSCALE")
>>> im.has_chrominance # -> False

height: int: image height

height_in_blocks(component: int) → int

Getter of height in blocks.

Parameters: component (int) – chroma component index (0 Y, 1 Cb, 2 Cr)
Returns: chroma component height
Return type: int
Raises: [IndexError] – when component index is out of range, dependent on number of components
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.height_in_blocks(0) # -> math.ceil(im.height/8)

Block dimension takes into account the chroma sampling factor for chrominance channels.

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.height_in_blocks(1)
>>> #=math.ceil(im.height/8*im.samp_factor[1, 0]/im.samp_factor[0, 0])
>>> im.height_in_blocks(2)
>>> #=math.ceil(im.height/8*im.samp_factor[2, 0]/im.samp_factor[0, 0])

Block dimensions are not initialized, when constructing from spatial domain.

>>> spatial = np.random.randint(0,255,(32,32,1),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.height_in_blocks(0) # -> None

property num_components: int

Getter of number of color components in the JPEG.

Returns: Number of color components.
Return type: bool
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.has_chrominance # -> 3

>>> im = jpeglib.read_spatial("input.jpeg", "JCS_GRAYSCALE")
>>> im.has_chrominance # -> 1

property num_markers: int

Getter of number of markers.

Returns: Number of markers.
Return type: int
Example

>>> im = jpeglib.read_spatial("input_2markers.jpeg")
>>> im.num_markers # -> 2

Synthetic JPEG has no markers in it.

>>> spatial = np.random.randint(0,255,(16,16,3),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.num_markers # -> 0

path: str: path to the jpeg file

progressive_mode: bool: indicator of progressive (True) or sequential (False) JPEG

samp_factor: Union[np.ndarray, str]: sampling factor; first is the channel, (0 Y, 1 Cb, 2 Cr), second is orientation (0 vertical, 1 horizontal) can be also specified as str in format ‘J:a:b’

property spatial: ndarray: pixel data tensors per scan

width: int: image width

width_in_blocks(component: int) → int

Getter of width in blocks.

Parameters: component (int) – chroma component index (0 Y, 1 Cb, 2 Cr)
Returns: chroma component width
Return type: int
Raises: [IndexError] – when component index is out of range, dependent on number of components
Example

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.width_in_blocks(0)
>>> #=math.ceil(im.width/8)

Block dimension takes into account the chroma sampling factor for chrominance channels.

>>> im = jpeglib.read_spatial("input.jpeg")
>>> im.width_in_blocks(1)
>>> #=math.ceil(im.width/8*im.samp_factor[1, 1]/im.samp_factor[0, 1])
>>> im.width_in_blocks(2)
>>> #=math.ceil(im.width/8*im.samp_factor[2, 1]/im.samp_factor[0, 1])

Block dimensions are not initialized, when constructing from spatial domain.

>>> spatial = np.random.randint(0,255,(32,32,1),dtype=np.uint8)
>>> im = jpeglib.from_spatial(spatial)
>>> im.height_in_blocks(0)
>>> #=None

write_spatial(path: str = None, qt: Union[int, ndarray] = None, quant_tbl_no: ndarray = None, base_quant_tbl_idx: int = None, dct_method: DCTMethod = None, smoothing_factor: int = None, flags: List[str] = [])

Writes a spatial image representation (i.e. RGB) to a file.

Parameters

path (str, optional) – Destination file name. If not given, source file is overwritten.
qt (int | numpy.ndarray, optional) – Compression quality, can be integer 0-100 or a tensor with quantization tables. Defaultly -1 (default factor kept).
quant_tbl_no (numpy.ndarray, optional) – assignment of quantization tables to components, (0 Y, 1 Cb, 1 Cr) by default
base_quant_tbl_idx (int, optional) – base QT to scale, only supported in MozJPEG 3+
dct_method (str | _dctmethod.DCTMethod, optional) – DCT method, must be accepted by _dctmethod.DCTMethod. If not given, using the libjpeg default.
smoothing_factor (int, optional) – Smoothing factor, between 0 and 100. Using default from libjpeg by default.
flags (list, optional) –
Bool compression parameters as str. If not given, using the libjpeg default. More at glossary.

Example

>>> jpeg = jpeglib.read_spatial("input.jpeg")
>>> jpeg.write_spatial("output.jpeg", qt=75)

Grayscale JPEG (only lumo channel) using libjpeg color conversion

>>> x = np.random.randint(0,255,(16,16,3),dtype=np.uint8)
>>> im = jpeglib.from_spatial(x)
>>> im.jpeg_color_space = jpeglib.JCS_GRAYSCALE
>>> im.write_spatial("hello.jpeg")

class jpeglib.Scan(components: 'np.ndarray' = <property object at 0x7248e00e3290>, dc_tbl_no: 'np.ndarray' = <property object at 0x7248e00e3240>, ac_tbl_no: 'np.ndarray' = <property object at 0x7248e00e31f0>, Ss: 'int' = <property object at 0x7248e00e31a0>, Se: 'int' = <property object at 0x7248e00e3150>, Ah: 'int' = <property object at 0x7248e00e30b0>, Al: 'int' = <property object at 0x7248e00e3970>)

property Ah: str

property Al: str

property Se: str

property Ss: str

property components: ndarray: index of components

Using jpegio interface 

jpeglib.to_jpegio(jpeg: DCTJPEG) → DCTJPEGio

Convertor of object of DCTJPEG to DCTJPEGio.

When DCTJPEG is converted to DCTJPEGio, the data objects DCTJPEG are not updated until writing. This behavior will be changed in the future.

Parameters: jpeg (DCTJPEG) – JPEG object to convert
Returns: converted JPEG object
Return type: DCTJPEGio
Example

>>> jpeg = jpeglib.read_dct("input.jpeg")
>>> jpeg = jpeglib.to_jpegio(jpeg)
>>> jpeg.coef_arrays; jpeg.quant_tables

class jpeglib.DCTJPEGio(path: str, content: bytes, height: int, width: int, block_dims: ~numpy.ndarray, samp_factor: ~typing.Union[~numpy.ndarray, str], markers: ~typing.List[~jpeglib._marker.Marker], huffmans: ~typing.List[~typing.Dict[str, ~jpeglib._huffman.Huffman]], jpeg_color_space: ~jpeglib._cenum.Colorspace, progressive_mode: bool, num_scans: int, Y: ~numpy.ndarray = <property object>, Cb: ~numpy.ndarray = <property object>, Cr: ~numpy.ndarray = <property object>, K: ~numpy.ndarray = <property object>, qt: ~numpy.ndarray = <property object>, quant_tbl_no: ~numpy.ndarray = <property object>, coef_arrays: ~typing.List = <property object>, quant_tables: ~typing.List = <property object>, comp_info: ~typing.List = <property object>)

Class for compatiblity with jpegio.

property coef_arrays: List: DCT coefficient arrays in jpegio format

property quant_tables: List: quantization tables in jpegio format

write(fpath: str, flags: int = -1, quality: int = -1)

Function to write DCT coefficients in jpegio format to JPEG file.

Does not perform JPEG compression, writing DCT is lossless.

Parameters

fpath (str, optional) – Destination file name. If not given, source file is overwritten.
flags (int) – Flags. For backward compatibility, does not make a difference.
quality (int, optional) – Compression quality, between 0 and 100. Special value -1 stands for using qt inside the instance or keeping libjpeg default.

Example

>>> jpeg = jpeglib.read_dct("input.jpeg")
>>> jpeg = jpeglib.to_jpegio(jpeg)
>>> jpeg.write("output.jpeg", quality=92)

libjpeg-like enumerations 

class jpeglib.Dithermode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Dithering mode.

JDITHER_FS = 2

JDITHER_NONE = 0: no dithering

JDITHER_ORDERED = 1

class jpeglib.Colorspace(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Representation of color space.

Carries information about number of channels.

JCS_CMYK = 4: CMYK

JCS_GRAYSCALE = 1: monochrome (luminance only)

JCS_RGB = 2: standard RGB

JCS_UNKNOWN = 0: unspecified color space

JCS_YCCK = 5: YCbCrK

JCS_YCbCr = 3: YCbCr or YUB, standard YCC

property channels: int: Number of channels that the color space has.

class jpeglib.DCTMethod(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Representation of DCT method.

JDCT_FLOAT = 2: floating point DCT

JDCT_IFAST = 1: fast integer DCT

JDCT_ISLOW = 0: slow integer DCT

class jpeglib.Marker(type: ~jpeglib._cenum.MarkerType, length: int = <property object>, content: bytes = <property object>)

Representation of JPEG marker.

property content: bytes: content of the marker

property length: int: length (in bytes)

type: MarkerType: type of marker

class jpeglib.MarkerType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Marker types.

JPEG_APP0 = 224

JPEG_APP1 = 225

JPEG_APP10 = 234

JPEG_APP11 = 235

JPEG_APP12 = 236

JPEG_APP13 = 237

JPEG_APP14 = 238

JPEG_APP15 = 239

JPEG_APP2 = 226

JPEG_APP3 = 227

JPEG_APP4 = 228

JPEG_APP5 = 229

JPEG_APP6 = 230

JPEG_APP7 = 231

JPEG_APP8 = 232

JPEG_APP9 = 233

JPEG_COM = 254

JPEG_EOI = 217

JPEG_RST0 = 208

JPEG_RST1 = 209

JPEG_RST2 = 210

JPEG_RST3 = 211

JPEG_RST4 = 212

JPEG_RST5 = 213

JPEG_RST6 = 214

JPEG_RST7 = 215

JPEG_RST8 = 216

libjpeg-like structures 

class jpeglib.Huffman(bits: 'np.ndarray' = <property object at 0x7248e00e0720>, values: 'np.ndarray' = <property object at 0x7248e00e0770>)

property bits: str: bits used to represent number of elements

property values: str: values, ordered by number of bits represented (i.e., histogram)

Manage libjpeg version 

class jpeglib.version(version)

Class grouping functions for controlling libjpeg method.

__enter__()

Sets new version in a block.

Example

>>> jpeglib.version.set('6b')
>>> # working with 6b
>>> # [...]
>>> with jpeglib.version('8d'):
>>>     # working with 8d
>>>     # [...]
>>>     pass

__exit__(*args, **kw)

Recovers a previous version, when exiting with block.

Example

>>> # working with 6b
>>> # [...]
>>> with jpeglib.version('8d'):
>>>     # working with 8d
>>>     # [...]
>>>     pass
>>> # working with 6b (again)
>>> # [...]

static get() → str

Gets the currently used version of libjpeg.

Returns: libjpeg version or None if not been loaded yet.
Return type: str, None
Example

>>> import jpeglib
>>> jpeglib.version.set('6b')
>>> jpeglib.version.get()
'6b'

classmethod set(version: str)

Sets the version of libjpeg to use. Loads the library.

Parameters: version (str) – libjpeg version, one of 6b, 7, 8, 8a, 8b, 8c, 8d, 9, 9a, 9b, 9c, 9d, 9e, 9f, turbo120, turbo130, turbo140, turbo150, turbo200, turbo210, mozjpeg101, mozjpeg201, mozjpeg300, mozjpeg403.
Raises: [NotImplementedError] – unsupported libjpeg version
Example

>>> import jpeglib
>>> jpeglib.version.set('8d')

static versions() → List[str]: Lists present DLLs of versions.