jyapayne/glymur
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Doc updates for writing XMP UUIDs. #104

Browse source
This commit is contained in:
jevans 2013-10-27 22:09:15 -04:00
commit 32760a6ecc
2 changed files with 56 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

84
docs/source/how_do_i.rst
View file

@ -4,7 +4,7 @@ How do I...?
... read the lowest resolution thumbnail? ... read the lowest resolution thumbnail?
===================================== =========================================
Printing the Jp2k object should reveal the number of resolutions (look in the Printing the Jp2k object should reveal the number of resolutions (look in the
COD segment section), but you can take a shortcut by supplying -1 as the COD segment section), but you can take a shortcut by supplying -1 as the
resolution level. :: resolution level. ::
@ -15,7 +15,7 @@ resolution level. ::
>>> thumbnail = j.read(rlevel=-1) >>> thumbnail = j.read(rlevel=-1)
... display metadata? ... display metadata?
================= =====================
There are two ways. From the unix command line, the script *jp2dump* is There are two ways. From the unix command line, the script *jp2dump* is
available. :: available. ::
@ -35,7 +35,7 @@ codestream box, only the main header is printed. It is possible to print
>>> print(j.get_codestream()) >>> print(j.get_codestream())
... add XML metadata? ... add XML metadata?
================= =====================
You can append any number of XML boxes to a JP2 file (not to a raw codestream). You can append any number of XML boxes to a JP2 file (not to a raw codestream).
Consider the following XML file `data.xml` : :: Consider the following XML file `data.xml` : ::
@ -66,12 +66,12 @@ The **append** method can add an XML box as shown below::
>>> jp2.append(xmlbox) >>> jp2.append(xmlbox)
>>> print(jp2) >>> print(jp2)
... add metadata in a more general fashion? ... add even more metadata?
======================================= ===========================
An existing raw codestream (or JP2 file) can be wrapped (re-wrapped) in a An existing raw codestream (or JP2 file) can be wrapped (re-wrapped) in a
user-defined set of JP2 boxes. To get just a minimal JP2 jacket on the user-defined set of JP2 boxes. To get just a minimal JP2 jacket on the
codestream provided by `goodstuff.j2k` (a file consisting of a raw codestream), codestream provided by `goodstuff.j2k` (a file consisting of a raw codestream),
you can use the **wrap** method with no box argument: :: you can use the :py:meth:`wrap` method with no box argument: ::
>>> import glymur >>> import glymur
>>> jfile = glymur.data.goodstuff() >>> jfile = glymur.data.goodstuff()
@ -108,8 +108,9 @@ JP2 header superbox.
XML boxes are not in the minimal set of box requirements for the JP2 format, so XML boxes are not in the minimal set of box requirements for the JP2 format, so
in order to add an XML box into the mix before the codestream box, we'll need to in order to add an XML box into the 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, re-specify all of the boxes. If you already have a JP2 jacket in place,
though. Take the following example content in an XML file `favorites.xml` : :: you can just reuse that, though. Take the following example content in
an XML file `favorites.xml` : ::
<?xml version="1.0"?> <?xml version="1.0"?>
<favorite_things> <favorite_things>
@ -152,13 +153,13 @@ the following will work. ::
. (truncated) . (truncated)
. .
As to the question of which method you should use, **append** or **wrap**, As to the question of which method you should use, :py:meth:`append` or
to add metadata, you should keep in mind that **wrap** produces a new JP2 file, :py:meth:`wrap`, to add metadata, you should keep in mind that :py:meth:`wrap`
while **append** modifies an existing file and is currently limited to XML produces a new JP2 file, while :py:meth:`append` modifies an existing file and
boxes. is currently limited to XML and UUID boxes.
... create an image with an alpha layer? ... create an image with an alpha layer?
==================================== ========================================
OpenJPEG can create JP2 files with more than 3 components (requires OpenJPEG can create JP2 files with more than 3 components (requires
the development version of OpenJPEG), but by default, any extra components are the development version of OpenJPEG), but by default, any extra components are
@ -219,32 +220,49 @@ Here's how the Preview application on the mac shows the RGBA image.
.. image:: goodstuff_alpha.png .. image:: goodstuff_alpha.png
work with XMP UUIDs? ... work with XMP UUIDs?
==================== ========================
The example JP2 file shipped with glymur has an XMP UUID. :: The example JP2 file shipped with glymur has an XMP UUID. ::
>>> import glymur >>> import glymur
>>> j = glymur.Jp2k(glymur.data.nemo()) >>> j = glymur.Jp2k(glymur.data.nemo())
>>> print(j.box[4]) >>> print(j.box[3]) # formatting added to the XML below
UUID Box (uuid) @ (715, 2412) <ns0:xmpmeta xmlns:dc="http://purl.org/dc/elements/1.1/"
UUID: be7acfcb-97a9-42e8-9c71-999491e3afac (XMP) xmlns:ns0="adobe:ns:meta/"
UUID Data: xmlns:ns2="http://ns.adobe.com/xap/1.0/"
<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"> xmlns:ns3="http://ns.adobe.com/tiff/1.0/"
xmlns:ns4="http://ns.adobe.com/exif/1.0/"
xmlns:ns5="http://ns.adobe.com/photoshop/1.0/"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
ns0:xmptk="Exempi + XMP Core 5.1.2">
<rdf:RDF> <rdf:RDF>
<rdf:Description ns2:CreatorTool="glymur" rdf:about="" /> .
</rdf:RDF> .
</ns0:xmpmeta> .
</ns0:xmpmeta>
Since the UUID data in this case is returned as an ElementTree instance, one can Since the UUID data in this case is returned as an ElementTree instance,
use ElementTree to access the data. For example, to extract the one can use ElementTree from the standard library to access the data.
**CreatorTool** attribute value, the following would work:: For example, to extract the **CreatorTool** attribute value, the following
would work::
>>> xmp = j.box[4].data >>> xmp = j.box[3].data.packet
>>> ns0 = '{http://www.w3.org/1999/02/22-rdf-syntax-ns#}' >>> rdf = '{http://www.w3.org/1999/02/22-rdf-syntax-ns#}'
>>> ns1 = '{http://ns.adobe.com/xap/1.0/}' >>> ns2 = '{http://ns.adobe.com/xap/1.0/}'
>>> name = '{0}RDF/{0}Description'.format(ns0) >>> name = '{0}RDF/{0}Description/{1}CreatorTool'.format(rdf, ns2)
>>> elt = xmp.find(name) >>> elt = xmp.find(name)
>>> elt >>> elt
<Element '{http://www.w3.org/1999/02/22-rdf-syntax-ns#}Description' at 0xb4baa93c> <Element '{http://ns.adobe.com/xap/1.0/#}CreatorTool' at 0xb50684a4>
>>> elt.attrib['{0}CreatorTool'.format(ns1)] >>> elt.text
'glymur' 'Google'
Yes, that's painful. A better solution is to install the Python XMP Toolkit
(developer branch)::
>>> from libxmp import XMPMeta
>>> from libxmp.consts import XMP_NS_XMP as NS_XAP
>>> meta = XMPMeta()
>>> meta.parse_from_str(j.box[3].raw_data.decode('utf-8'))
>>> meta.get_property(NS_XAP, 'CreatorTool')
'Google'

12
docs/source/introduction.rst
View file

@ -7,11 +7,9 @@ which allows one to read and write JPEG 2000 files from within Python.
Glymur supports both reading and writing of JPEG 2000 images, but writing Glymur supports both reading and writing of JPEG 2000 images, but writing
JPEG 2000 images is currently limited to images that can fit in memory JPEG 2000 images is currently limited to images that can fit in memory
Of particular focus is retrieval of metadata. Reading Exif UUIDs is supported, In regards to metadata, most JP2 boxes are properly interpreted.
as is reading XMP UUIDs as the XMP data packet is just XML. There is Certain optional JP2 boxes can also be written, including XML boxes and
some very limited support for reading JPX metadata. For instance, XMP UUIDs. There is some very limited support for reading JPX metadata.
**asoc** and **labl** boxes are recognized, so GMLJP2 metadata can
be retrieved from such JPX files.
Glymur works on Python 2.6, 2.7, and 3.3. Glymur works on Python 2.6, 2.7, and 3.3.
@ -20,8 +18,8 @@ OpenJPEG Installation
Glymur will read JPEG 2000 images with versions 1.3, 1.4, 1.5, 2.0, Glymur will read JPEG 2000 images with versions 1.3, 1.4, 1.5, 2.0,
and the trunk/development version of OpenJPEG. Writing images is and the trunk/development version of OpenJPEG. Writing images is
only supported with the 1.5 or better, however, and the trunk/development only supported with the 1.5 or better, however, and the trunk/development
version is strongly recommended. For more information about OpenJPEG, version of OpenJPEG is strongly recommended. For more information about
please consult http://www.openjpeg.org. OpenJPEG, please consult http://www.openjpeg.org.
If you use MacPorts or if you have a sufficiently recent version of If you use MacPorts or if you have a sufficiently recent version of
Linux, your package manager should already provide you with a version of Linux, your package manager should already provide you with a version of