glymur Documentation - Read the Docs · glymur Documentation, Release 0.5.12 The raw codestream was...

glymur DocumentationRelease 0.5.12

John Evans

May 18, 2014

Contents

i

glymur Documentation, Release 0.5.12

Contents:

Contents 1


2 Contents

CHAPTER 1

Glymur: a Python interface for JPEG 2000

Glymur is an interface to the OpenJPEG library which allows one to read and write JPEG 2000 files from Python.Glymur supports both reading and writing of JPEG 2000 images, but writing JPEG 2000 images is currently limitedto images that can fit in memory

Of particular focus is retrieval of metadata. Reading Exif UUIDs is supported, as is reading XMP UUIDs as the XMPdata packet is just XML. There is some very limited support for reading JPX metadata. For instance, asoc and lablboxes are recognized, so GMLJP2 metadata can be retrieved from such JPX files.

Glymur works on Python 2.6, 2.7, 3.3, and 3.4.

1.1 OpenJPEG Installation

Glymur will read JPEG 2000 images with versions 1.3, 1.4, 1.5, 2.0, and 2.1 of OpenJPEG. Writing images is onlysupported with OpenJPEG 1.5 or better, however, and version 2.1 is strongly recommended. For more informationabout OpenJPEG, please consult http://www.openjpeg.org.

If you use MacPorts or if you have a sufficiently recent version of Linux, your package manager should already provideyou with a version of OpenJPEG 1.X which glymur can already use. If your platform is windows, I suggest using thewindows installers provided to you by the OpenJPEG folks at https://code.google.com/p/openjpeg/downloads/list .

1.2 Glymur Installation

You can retrieve the source for Glymur from either of

• https://pypi.python.org/pypi/Glymur/ (stable releases)

• http://github.com/quintusdias/glymur (bleeding edge)

but you should also be able to install Glymur via pip

$ pip install glymur

This will install the jp2dump script that can be used from the unix command line, so you should adjust your $PATHto take advantage of it. For example, if you install with pip’s –user option on linux

$ export PATH=$HOME/.local/bin:$PATH

3

http://www.openjpeg.org

https://code.google.com/p/openjpeg/downloads/list

https://pypi.python.org/pypi/Glymur/

http://github.com/quintusdias/glymur


4 Chapter 1. Glymur: a Python interface for JPEG 2000

CHAPTER 2

Advanced Installation Instructions

2.1 Glymur Configuration

The default glymur installation process relies upon OpenJPEG being properly installed on your system as a sharedlibrary. If you have OpenJPEG installed through your system’s package manager on linux or if you use MacPorts onthe mac, you are probably already set to go. But if you have OpenJPEG installed into a non-standard place or if youuse windows, then read on.

Glymur uses ctypes to access the openjp2/openjpeg libraries, and because ctypes accesses libraries in a platform-dependent manner, it is recommended that if you compile and install OpenJPEG into a non-standard location, youshould then create a configuration file to help Glymur properly find the openjpeg or openjp2 libraries (linux users ormacports users don’t need to bother with this if you are using OpenJPEG as provided by your package manager). Theconfiguration format is the same as used by Python’s configparser module, i.e.

[library]openjp2: /opt/openjp2-svn/lib/libopenjp2.so

This assumes, of course, that you’ve installed OpenJPEG into /opt/openjp2-svn on a linux system. The location of theconfiguration file can vary as well. If you use either linux or mac, the path to the configuration file would normally be

$HOME/.config/glymur/glymurrc

but if you have the XDG_CONFIG_HOME environment variable defined, the path will be

$XDG_CONFIG_HOME/glymur/glymurrc

On windows, the path to the configuration file can be determined by starting up Python and typing

import osos.path.join(os.path.expanduser(’~’), ’glymur’, ’glymurrc’)

You may also include a line for the version 1.x openjpeg library if you have it installed in a non-standard place, i.e.

[library]openjpeg: /not/the/usual/location/lib/libopenjpeg.so

2.2 Testing

It is not necessary, but you may wish to download OpenJPEG’s test data for the purpose of configuring and run-ning OpenJPEG’s test suite. Check their instructions on how to do that. You can then set the OPJ_DATA_ROOTenvironment variable for the purpose of pointing Glymur to OpenJPEG’s test suite.

5


$ svn co http://openjpeg.googlecode.com/svn/data$ export OPJ_DATA_ROOT=‘pwd‘/data

In order to run the tests, you can either run them from within python as follows ...

>>> import glymur>>> glymur.runtests()

or from the command line.

$ cd /to/where/you/unpacked/glymur$ python -m unittest discover

6 Chapter 2. Advanced Installation Instructions

CHAPTER 3

How do I...?

3.1 ... read the lowest resolution thumbnail?

Printing the Jp2k object should reveal the number of resolutions (look in the COD segment section), but you can takea shortcut by supplying -1 as the resolution level.

>>> import glymur>>> file = glymur.data.nemo()>>> j = glymur.Jp2k(file)>>> thumbnail = j.read(rlevel=-1)

3.2 ... display metadata?

There are two ways. From the unix command line, the script jp2dump is available.

$ jp2dump /path/to/glymur/installation/data/nemo.jp2

From within Python, it is as simple as printing the Jp2k object, i.e.

>>> from glymur import Jp2k>>> file = glymur.data.nemo()>>> j = Jp2k(file)>>> print(j)

This prints the metadata found in the JP2 boxes, but in the case of the codestream box, only the main header is printed.It is possible to print only the codestream information as well, i.e.

>>> print(j.get_codestream())

3.3 ... add XML metadata?

You can append any number of XML boxes to a JP2 file (not to a raw codestream). Consider the following XML filedata.xml :

<?xml version="1.0"?><info>

<locality><city>Boston</city>

7


<snowfall>24.9 inches</snowfall></locality><locality>

<city>Portland</city><snowfall>31.9 inches</snowfall>

</locality><locality>

<city>New York City</city><snowfall>11.4 inches</snowfall>

</locality></info>

The append method can add an XML box as shown below:

>>> import shutil>>> import glymur>>> shutil.copyfile(glymur.data.nemo(), ’myfile.jp2’)>>> from xml.etree import cElementTree as ET>>> jp2 = glymur.Jp2k(’myfile.jp2’)>>> xmlbox = glymur.jp2box.XMLBox(filename=’data.xml’)>>> jp2.append(xmlbox)>>> print(jp2)

3.4 ... add metadata in a more general fashion?

An existing raw codestream or JP2 file can be wrapped (re-wrapped in the case of JP2) in a user-defined set of JP2boxes. To get just a minimal JP2 jacket on the codestream provided by goodstuff.j2k (a file consisting of just a rawcodestream), you can use the wrap method with no box argument:

>>> import glymur>>> jfile = glymur.data.goodstuff()>>> j2k = glymur.Jp2k(jfile)>>> jp2 = j2k.wrap("newfile.jp2")>>> print(jp2)File: newfile.jp2JPEG 2000 Signature Box (jP ) @ (0, 12)

Signature: 0d0a870aFile Type Box (ftyp) @ (12, 20)

Brand: jp2Compatibility: [’jp2 ’]

JP2 Header Box (jp2h) @ (32, 45)Image Header Box (ihdr) @ (40, 22)

Size: [800 480 3]Bitdepth: 8Signed: FalseCompression: waveletColorspace Unknown: False

Colour Specification Box (colr) @ (62, 15)Method: enumerated colorspacePrecedence: 0Colorspace: sRGB

Contiguous Codestream Box (jp2c) @ (77, 115228)Main header:.. (truncated).

8 Chapter 3. How do I...?


The raw codestream was wrapped in a JP2 jacket with four boxes in the outer layer (the signature, file type, JP2 header,and contiguous codestream), with two additional boxes (image header and color specification) contained in the JP2header superbox.

XML boxes are not in the minimal set of box requirements for the JP2 format, so in order to add an XML box intothe mix before the codestream box, we’ll need to re-specify all of the boxes. If you already have a JP2 jacket in place,you can just reuse that, though. Take the following example content in an XML file favorites.xml :

<?xml version="1.0"?><favorite_things>

<category>Light Ale</category></favorite_things>

In order to add the XML after the JP2 header box, but before the codestream box, the following will work.

>>> boxes = jp2.box # The box attribute is the list of JP2 boxes>>> xmlbox = glymur.jp2box.XMLBox(filename=’favorites.xml’)>>> boxes.insert(3, xmlbox)>>> jp2_xml = jp2.wrap("newfile_with_xml.jp2", boxes=boxes)>>> print(jp2_xml)File: newfile_with_xml.jp2JPEG 2000 Signature Box (jP ) @ (0, 12)

Signature: 0d0a870aFile Type Box (ftyp) @ (12, 20)

Brand: jp2Compatibility: [’jp2 ’]

JP2 Header Box (jp2h) @ (32, 45)Image Header Box (ihdr) @ (40, 22)

Size: [800 480 3]Bitdepth: 8Signed: FalseCompression: waveletColorspace Unknown: False

Colour Specification Box (colr) @ (62, 15)Method: enumerated colorspacePrecedence: 0Colorspace: sRGB

XML Box (xml ) @ (77, 76)<favorite_things>

<category>Light Ale</category></favorite_things>

Contiguous Codestream Box (jp2c) @ (153, 115236)Main header:.. (truncated).

As to the question of which method you should use, append or wrap, to add metadata, you should keep in mind thatwrap produces a new JP2 file, while append modifies an existing file and is currently limited to XML boxes.

3.5 ... create an image with an alpha layer?

OpenJPEG can create JP2 files with more than 3 components (requires version 2.1), but by default any extra compo-nents are not described as such by the JP2 boxes created by OpenJPEG. In order to do so, we need to rewrap such animage in a set of boxes that includes a channel definition box.

3.5. ... create an image with an alpha layer? 9


This example is based on SciPy example code found at http://scipy-lectures.github.io/advanced/image_processing/#basic-manipulations . Instead of a circular mask we’ll make it an ellipse since the source image isn’t square.

>>> import numpy as np>>> import glymur>>> from glymur import Jp2k>>> rgb = Jp2k(glymur.data.goodstuff()).read()>>> lx, ly = rgb.shape[0:2]>>> X, Y = np.ogrid[0:lx, 0:ly]>>> mask = ly**2*(X - lx / 2) ** 2 + lx**2*(Y - ly / 2) ** 2 > (lx * ly / 2)**2>>> alpha = 255 * np.ones((lx, ly, 1), dtype=np.uint8)>>> alpha[mask] = 0>>> rgba = np.concatenate((rgb, alpha), axis=2)>>> jp2 = Jp2k(’tmp.jp2’, ’wb’)>>> jp2.write(rgba)

Next we need to specify what types of channels we have. The first three channels are color channels, but we identifythe fourth as an alpha channel:

>>> from glymur.core import COLOR, OPACITY>>> ctype = [COLOR, COLOR, COLOR, OPACITY]

And finally we have to specify just exactly how each channel is to be interpreted. The color channels are straight-forward, they correspond to R-G-B, but the alpha (or opacity) channel in this case is to be applied against the entireimage (it is possible to apply an alpha channel to a single color channel, but we aren’t doing that).

>>> from glymur.core import RED, GREEN, BLUE, WHOLE_IMAGE>>> asoc = [RED, GREEN, BLUE, WHOLE_IMAGE]>>> cdef = glymur.jp2box.ChannelDefinitionBox(channel_type=ctype, association=asoc)>>> print(cdef)Channel Definition Box (cdef) @ (0, 0)

Channel 0 (color) ==> (1)Channel 1 (color) ==> (2)Channel 2 (color) ==> (3)Channel 3 (opacity) ==> (whole image)

It’s easiest to take the existing jp2 jacket and just add the channel definition box in the appropriate spot. The channeldefinition box must go into the jp2 header box, and then we can rewrap the image.

>>> boxes = jp2.box # The box attribute is the list of JP2 boxes>>> boxes[2].box.append(cdef)>>> jp2_rgba = jp2.wrap("goodstuff_rgba.jp2", boxes=boxes)

Here’s how the Preview application on the mac shows the RGBA image.


http://scipy-lectures.github.io/advanced/image_processing/#basic-manipulations

http://scipy-lectures.github.io/advanced/image_processing/#basic-manipulations


3.5. ... create an image with an alpha layer? 11


3.6 ... work with XMP UUIDs?

The example JP2 file shipped with glymur has an XMP UUID.

>>> import glymur>>> j = glymur.Jp2k(glymur.data.nemo())>>> print(j.box[4])UUID Box (uuid) @ (715, 2412)

UUID: be7acfcb-97a9-42e8-9c71-999491e3afac (XMP)UUID Data:<ns0:xmpmeta xmlns:ns0="adobe:ns:meta/" xmlns:ns2="http://ns.adobe.com/xap/1.0/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" ns0:xmptk="XMP Core 4.4.0-Exiv2">

<rdf:RDF><rdf:Description ns2:CreatorTool="glymur" rdf:about="" />

</rdf:RDF></ns0:xmpmeta>

Since the UUID data in this case is returned as an ElementTree instance, one can use ElementTree to access the data.For example, to extract the CreatorTool attribute value, the following would work:

>>> xmp = j.box[4].data>>> ns0 = ’{http://www.w3.org/1999/02/22-rdf-syntax-ns#}’>>> ns1 = ’{http://ns.adobe.com/xap/1.0/}’>>> name = ’{0}RDF/{0}Description’.format(ns0)>>> elt = xmp.find(name)>>> elt<Element ’{http://www.w3.org/1999/02/22-rdf-syntax-ns#}Description’ at 0xb4baa93c>>>> elt.attrib[’{0}CreatorTool’.format(ns1)]’glymur’


CHAPTER 4

API

4.1 Jp2k

class glymur.Jp2k(filename, mode=’rb’)JPEG 2000 file.

Attributes

file-name

str The path to the JPEG 2000 file.

mode str The mode used to open the file.box se-

quenceList of top-level boxes in the file. Each box may in turn contain its own list of boxes. Willbe empty if the file consists only of a raw codestream.

Methods

appendget_codestreamparseparse_superboxreadread_bandswrapwrite

get_codestream(header_only=True)Returns a codestream object.

Parameters header_only : bool, optional

If True, only marker segments in the main header are parsed. Supplying False mayimpose a large performance penalty.

Returns Object describing the codestream syntax. :

Raises IOError :

If the file is JPX with more than one codestream.

13


Examples

>>> import glymur>>> jfile = glymur.data.nemo()>>> jp2 = glymur.Jp2k(jfile)>>> codestream = jp2.get_codestream()>>> print(codestream.segment[1])SIZ marker segment @ (3137, 47)

Profile: 2Reference Grid Height, Width: (1456 x 2592)Vertical, Horizontal Reference Grid Offset: (0 x 0)Reference Tile Height, Width: (1456 x 2592)Vertical, Horizontal Reference Tile Offset: (0 x 0)Bitdepth: (8, 8, 8)Signed: (False, False, False)Vertical, Horizontal Subsampling: ((1, 1), (1, 1), (1, 1))

read(**kwargs)Read a JPEG 2000 image.

Parameters rlevel : int, optional

Factor by which to rlevel output resolution. Use -1 to get the lowest resolution thumb-nail. This is the only keyword option available to use when only the OpenJPEG version1.5.1 is present.

layer : int, optional

Number of quality layer to decode.

area : tuple, optional

Specifies decoding image area, (first_row, first_col, last_row, last_col)

tile : int, optional

Number of tile to decode.

verbose : bool, optional

Print informational messages produced by the OpenJPEG library.

Returns img_array : ndarray

The image data.

Raises glymur.LibraryNotFoundError :

If glymur is unable to load either the openjpeg or openjp2 libraries.

IOError :

If the image has differing subsample factors.

Examples

>>> import glymur>>> jfile = glymur.data.nemo()>>> jp = glymur.Jp2k(jfile)>>> image = jp.read()>>> image.shape(1456, 2592, 3)

14 Chapter 4. API


Read the lowest resolution thumbnail.

>>> thumbnail = jp.read(rlevel=-1)>>> thumbnail.shape(728, 1296, 3)

read_bands(rlevel=0, layer=0, area=None, tile=None, verbose=False)Read a JPEG 2000 image.

The only time you should use this method is when the image has different subsampling factors acrosscomponents. Otherwise you should use the read method.

Parameters layer : int, optional

Number of quality layer to decode.

rlevel : int, optional

Factor by which to rlevel output resolution.

area : tuple, optional

Specifies decoding image area, (first_row, first_col, last_row, last_col)

tile : int, optional

Number of tile to decode.



Returns lst : list

The individual image components.


If glymur is unable to load the openjp2 library.

See also:

read read JPEG 2000 image

Examples

>>> import glymur>>> jfile = glymur.data.nemo()>>> jp = glymur.Jp2k(jfile)>>> components_lst = jp.read_bands(rlevel=1)

wrap(filename, boxes=None)Write the codestream back out to file, wrapped in new JP2 jacket.

Parameters filename : str

JP2 file to be created from a raw codestream.

boxes : list

JP2 box definitions to define the JP2 file format. If not provided, a default “”jacket” isassumed, consisting of JP2 signature, file type, JP2 header, and contiguous codestreamboxes.

Returns jp2 : Jp2k object

4.1. Jp2k 15


Newly wrapped Jp2k object.

Examples

>>> import glymur, tempfile>>> jfile = glymur.data.goodstuff()>>> j2k = glymur.Jp2k(jfile)>>> tfile = tempfile.NamedTemporaryFile(suffix=’jp2’)>>> jp2 = j2k.wrap(tfile.name)

write(img_array, verbose=False, **kwargs)Write image data to a JP2/JPX/J2k file. Intended usage of the various parameters follows that of Open-JPEG’s opj_compress utility.

This method can only be used to create JPEG 2000 images that can fit in memory.

Parameters img_array : ndarray

Image data to be written to file.

cbsize : tuple, optional

Code block size (DY, DX).

colorspace : str, optional

Either ‘rgb’ or ‘gray’.

cratios : iterable

Compression ratios for successive layers.

eph : bool, optional

If true, write SOP marker after each header packet.

grid_offset : tuple, optional

Offset (DY, DX) of the origin of the image in the reference grid.

mct : bool, optional

Specifies usage of the multi component transform. If not specified, defaults to True ifthe colorspace is RGB.

modesw : int, optional

Mode switch. 1 = BYPASS(LAZY) 2 = RESET 4 = RESTART(TERMALL) 8 = VSC16 = ERTERM(SEGTERM) 32 = SEGMARK(SEGSYM)

numres : int, optional

Number of resolutions.

prog : str, optional

Progression order, one of “LRCP” “RLCP”, “RPCL”, “PCRL”, “CPRL”.

psnr : iterable, optional

Different PSNR for successive layers.

psizes : list, optional

List of precinct sizes. Each precinct size tuple is defined in (height x width).

16 Chapter 4. API


sop : bool, optional

If true, write SOP marker before each packet.

subsam : tuple, optional

Subsampling factors (dy, dx).

tilesize : tuple, optional

Numeric tuple specifying tile size in terms of (numrows, numcols), not (X, Y).




If glymur is unable to load the openjp2 library.

Examples

>>> import glymur>>> jfile = glymur.data.nemo()>>> jp2 = glymur.Jp2k(jfile)>>> data = jp2.read(rlevel=1)>>> from tempfile import NamedTemporaryFile>>> tfile = NamedTemporaryFile(suffix=’.jp2’, delete=False)>>> j = Jp2k(tfile.name, mode=’wb’)>>> j.write(data.astype(np.uint8))

4.2 Individual Boxes

4.2.1 Jp2kbox

class glymur.jp2box.Jp2kBox(box_id=’‘, offset=0, length=0, longname=’‘)Superclass for JPEG 2000 boxes.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.

Methods

parse_superboxwrite

parse_superbox(fptr)Parse a superbox (box consisting of nothing but other boxes.

4.2. Individual Boxes 17


Parameters fptr : file

Open file object.

Returns List of top-level boxes in the JPEG 2000 file. :

write(_)Must be implemented in a subclass.

4.2.2 AssociationBox

class glymur.jp2box.AssociationBox(length=0, offset=-1)Container for Association box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.box list List of boxes contained in this superbox.

Methods

parseparse_superboxwrite

static parse(fptr, offset, length)Parse association box.


Open file object.

offset : int

Start position of box in bytes.

length : int

Length of the box in bytes.

Returns AssociationBox instance :

4.2.3 ColourSpecificationBox

class glymur.jp2box.ColourSpecificationBox(method=1, precedence=0, approximation=0,colorspace=None, icc_profile=None, length=0,offset=-1)

Container for JPEG 2000 color specification box information.

18 Chapter 4. API


Attributes

box_id str 4-character identifier for the box.length int Length of the box in bytes.offset int Offset of the box from the start of the file.longname str More verbose description of the box.method int Method for defining the colorspace.prece-dence

int How this box ranks in priority compared to other color specification boxes.

approxi-mation

int Measure of colorspace accuracy.

col-orspace

int orNone

Enumerated colorspace, corresponds to one of ‘sRGB’, ‘greyscale’, or ‘YCC’. Ifnot None, then icc_profile must be None.

icc_profile dict ICC profile header according to ICC profile specification. If colorspace is not None,then icc_profile must be empty.

Methods


static parse(fptr, offset, length)Parse JPEG 2000 color specification box.


Open file object.

offset : int


length : int


Returns ColourSpecificationBox instance :

write(fptr)Write an Colour Specification box to file.

4.2.4 ChannelDefinitionBox

class glymur.jp2box.ChannelDefinitionBox(index=None, channel_type=None, associa-tion=None, **kwargs)

Container for component definition box information.



Attributes

box_id str 4-character identifier for the box.length numeric

scalarlength of the box in bytes.

offset int offset of the box from the start of the file.longname str more verbose description of the box.index int number of the channel. Defaults to monotonically increasing sequence, i.e.

[0, 1, 2, ...]chan-nel_type

int type of the channel

association int index of the associated color

Methods


static parse(fptr, offset, length)Parse component definition box.


Open file object.

offset : int


length : int


Returns ComponentDefinitionBox instance :

write(fptr)Write a channel definition box to file.

4.2.5 ComponentMappingBox

class glymur.jp2box.ComponentMappingBox(component_index, mapping_type, palette_index,length=0, offset=-1)

Container for component mapping information.

20 Chapter 4. API


Attributes

box_id str 4-character identifier for the box.length numeric scalar Length of the box in bytes.offset int Offset of the box from the start of the file.longname str Verbose description of the box.component_index int Index of component in codestream that is mapped to this channel.mapping_type int mapping type, either direct use (0) or palette (1)palette_index int Index component from palette

Methods


static parse(fptr, offset, length)Parse component mapping box.


Open file object.

offset : int


length : int


Returns ComponentMappingBox instance :

4.2.6 ContiguousCodestreamBox

class glymur.jp2box.ContiguousCodestreamBox(main_header=None, length=0, offset=-1)Container for JPEG2000 codestream information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.main_header list List of segments in the codestream header.

Methods




static parse(fptr, offset=0, length=0)Parse a codestream box.


Open file object.

offset : int


length : int


Returns ContiguousCodestreamBox instance :

4.2.7 DataEntryURLBox

class glymur.jp2box.DataEntryURLBox(version, flag, url, length=0, offset=-1)Container for data entry URL box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.version byte Must be 0 for JP2.flag bytes Particular attributes of this box, consists of three bytes.URL str Associated URL.

Methods


static parse(fptr, offset, length)Parse data entry URL box.


Open file object.

offset : int


length : int


Returns DataEntryURLbox instance :

22 Chapter 4. API


4.2.8 FileTypeBox

class glymur.jp2box.FileTypeBox(brand=’jp2 ‘, minor_version=0, compatibility_list=None,length=0, offset=-1)

Container for JPEG 2000 file type box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.brand: str Specifies the governing recommendation or standard upon which this file is

based.minor_version: int Minor version number identifying the JP2 specification used.compatibility_list:list

List of file conformance profiles.

Methods


static parse(fptr, offset, length)Parse JPEG 2000 file type box.

Parameters f : file

Open file object.

offset : int


length : int


Returns FileTypeBox instance :

write(fptr)Write a File Type box to file.

4.2.9 ImageHeaderBox

class glymur.jp2box.ImageHeaderBox(height, width, num_components=1, signed=False,bits_per_component=8, compression=7, col-orspace_unknown=False, ip_provided=False, length=0,offset=-1)

Container for JPEG 2000 image header box information.



Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.height, width int Height and width of image.num_components int Number of image channels.bits_per_component int Bits per component.signed bool False if the image components are unsigned.compression int The compression type, should be 7 if JP2.colorspace_unknown bool False if the color space is known and correctly specified.ip_provided bool False if the file does not contain intellectual propery rights information.

Methods


static parse(fptr, offset, length)Parse JPEG 2000 image header box.


Open file object.

offset : int


length : int


Returns ImageHeaderBox instance :

write(fptr)Write an Image Header box to file.

4.2.10 JP2HeaderBox

class glymur.jp2box.JP2HeaderBox(length=0, offset=-1)Container for JP2 header box information.

Attributes


24 Chapter 4. API


Methods


static parse(fptr, offset, length)Parse JPEG 2000 header box.


Open file object.

offset : int


length : int


Returns JP2HeaderBox instance :

write(fptr)Write a JP2 Header box to file.

4.2.11 JPEG2000SignatureBox

class glymur.jp2box.JPEG2000SignatureBox(signature=(13, 10, 135, 10), length=0, offset=-1)Container for JPEG 2000 signature box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.signature byte Four-byte tuple identifying the file as JPEG 2000.

Methods


static parse(fptr, offset, length)Parse JPEG 2000 signature box.


Open file object.

offset : int




length : int


Returns JPEG2000SignatureBox instance :

write(fptr)Write a JPEG 2000 Signature box to file.

4.2.12 LabelBox

class glymur.jp2box.LabelBox(label, length=0, offset=-1)Container for Label box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.label str Label

Methods


static parse(fptr, offset, length)Parse Label box.


Open file object.

offset : int


length : int


Returns LabelBox instance :

4.2.13 PaletteBox

class glymur.jp2box.PaletteBox(palette, bits_per_component, signed, length=0, offset=-1)Container for palette box information.

26 Chapter 4. API


Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.palette list Colormap represented as list of 1D arrays, one per color component.

Methods


static parse(fptr, offset, length)Parse palette box.


Open file object.

offset : int


length : int


Returns PaletteBox instance :

4.2.14 ReaderRequirementsBox

class glymur.jp2box.ReaderRequirementsBox(fuam, dcm, standard_flag, standard_mask, ven-dor_feature, vendor_mask, length=0, offset=-1)

Container for reader requirements box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.fuam int Fully Understand Aspects mask.dcm int Decode completely mask.standard_flag list Integers specifying standard features.standard_mask list Specifies the compatibility mask for each corresponding standard flag.vendor_feature list Each item is a UUID corresponding to a vendor defined feature.vendor_mask list Specifies the compatibility mask for each corresponding vendor feature.

Methods




static parse(fptr, offset, length)Parse reader requirements box.


Open file object.

offset : int


length : int


Returns ReaderRequirementsBox instance :

4.2.15 ResolutionBox

class glymur.jp2box.ResolutionBox(length=0, offset=-1)Container for Resolution superbox information.

Attributes


Methods


static parse(fptr, offset, length)Parse Resolution box.


Open file object.

offset : int


length : int


28 Chapter 4. API


Returns ResolutionBox instance :

4.2.16 CaptureResolutionBox

class glymur.jp2box.CaptureResolutionBox(vertical_resolution, horizontal_resolution, length=0,offset=-1)

Container for Capture resolution box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.vertical_resolution, horizontal_resolution float Vertical, horizontal resolution.

Methods


static parse(fptr, offset, length)Parse CaptureResolutionBox.


Open file object.

offset : int


length : int


Returns CaptureResolutionBox instance :

4.2.17 DisplayResolutionBox

class glymur.jp2box.DisplayResolutionBox(vertical_resolution, horizontal_resolution, length=0,offset=-1)

Container for Display resolution box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.vertical_resolution, horizontal_resolution float Vertical, horizontal resolution.



Methods


static parse(fptr, offset, length)Parse display resolution box.


Open file object.

offset : int


length : int


Returns DisplayResolutionBox instance :

4.2.18 UUIDBox

class glymur.jp2box.UUIDBox(the_uuid, raw_data, length=0, offset=-1)Container for UUID box information.

References

[XMP]

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.long-name

str more verbose description of the box.

uuid uuid.UUID 16-byte UUIDdata bytes or dict or

ElementTree.ElementVendor-specific data. Exif UUIDs are interpreted as dictionaries. XMPUUIDs are interpreted as standard XML.

Methods


static parse(fptr, offset, length)Parse UUID box.

30 Chapter 4. API



Open file object.

offset : int


length : int


Returns UUIDBox instance :

4.2.19 UUIDInfoBox

class glymur.jp2box.UUIDInfoBox(length=0, offset=-1)Container for JPEG 2000 UUID Info superbox.

Attributes


Methods


static parse(fptr, offset, length)Parse UUIDInfo super box.


Open file object.

offset : int


length : int


Returns UUIDInfoBox instance :

4.2.20 UUIDListBox

class glymur.jp2box.UUIDListBox(ulst, length=0, offset=-1)Container for JPEG 2000 UUID list box.



Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.ulst list List of UUIDs.

Methods


static parse(fptr, offset, length)Parse UUIDList box.

Parameters f : file

Open file object.

offset : int


length : int


Returns UUIDListBox instance :

4.2.21 XMLBox

class glymur.jp2box.XMLBox(xml=None, filename=None, length=0, offset=-1)Container for XML box information.

Attributes

box_id str 4-character identifier for the box.length int length of the box in bytes.offset int offset of the box from the start of the file.longname str more verbose description of the box.xml ElementTree object XML section.

Methods


32 Chapter 4. API


static parse(fptr, offset, length)Parse XML box.


Open file object.

offset : int


length : int


Returns XMLBox instance :

write(fptr)Write an XML box to file.



34 Chapter 4. API

CHAPTER 5

Roadmap

Here’s an incomplete list of what I’d like to focus on in the future.

• continue to monitor upstream changes in the openjp2 library

• investigate using CFFI or cython instead of ctypes to wrap openjp2

• investigate adding write support for UUID/XMP boxes (potentially a big project)

• investigate JPIP (likely to be an even bigger project)

Support for Python 2.6 will be dropped with the 0.6.0 release.

35


36 Chapter 5. Roadmap

CHAPTER 6

“What’s new” documents

These document the changes between minor (or major) versions of glymur.

6.1 Changes in glymur 0.5

6.1.1 Changes in 0.5.12

• Minor documentation fixes for grammar and style.

• The functions removed in 0.5.11 due to API changes in OpenJPEG 2.1.0 were restored for backwards compati-bility. They are deprecated, though, and will be removed in 0.6.0.

– glymur.lib.openjp2.stream_create_default_file_stream_v3

– glymur.lib.openjp2.opj.stream_destroy_v3

6.1.2 Changes in 0.5.11

• Added support for Python 3.4.

• OpenJPEG 1.5.2 and 2.0.1 are officially supported.

• OpenJPEG 2.1.0 is officially supported, but the ABI changes introduced by OpenJPEG 2.1.0 required corre-sponding changes to glymur’s ctypes interface. The functions

– glymur.lib.openjp2.stream_create_default_file_stream_v3

– glymur.lib.openjp2.opj.stream_destroy_v3

functions were renamed to

– glymur.lib.openjp2.stream_create_default_file_stream

– glymur.lib.openjp2.opj.stream_destroy

in order to follow OpenJPEG’s upstream changes. Unless you were using the svn version of OpenJPEG, youshould not be affected by this.

6.1.3 Changes in 0.5.10

• Fixed bad warning issued when an unsupported reader requirement box mask length was encountered.

37


6.1.4 Changes in 0.5.9

• Fixed bad library load on linux as a result of botched 0.5.8 release. This release was primarily aimed at support-ing SunPy.

38 Chapter 6. “What’s new” documents

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

39


40 Chapter 7. Indices and tables

Bibliography

[XMP] International Organization for Standardication. ISO/IEC 16684-1:2012 - Graphic technology – Extensiblemetadata platform (XMP) specification – Part 1: Data model, serialization and core properties

41

glymur Documentation - Read the Docs · glymur Documentation, Release 0.5.12 The raw codestream was...

Documents

Transcript of glymur Documentation - Read the Docs · glymur Documentation, Release 0.5.12 The raw codestream was...