diff --git a/docs/source/how_do_i.rst b/docs/source/how_do_i.rst index 01dd24c..dde5b60 100644 --- a/docs/source/how_do_i.rst +++ b/docs/source/how_do_i.rst @@ -11,8 +11,8 @@ resolution level. :: >>> import glymur >>> file = glymur.data.nemo() - >>> j = glymur.Jp2k(file) - >>> thumbnail = j.read(rlevel=-1) + >>> jp2 = glymur.Jp2k(file) + >>> thumbnail = jp2.read(rlevel=-1) ... display metadata? ===================== @@ -23,16 +23,183 @@ available. :: From within Python, it is as simple as printing the Jp2k object, i.e. :: - >>> from glymur import Jp2k + >>> import glymur >>> file = glymur.data.nemo() - >>> j = Jp2k(file) - >>> print(j) + >>> jp2 = glymur.Jp2k(file) + >>> print(jp2) + File: nemo.jp2 + JPEG 2000 Signature Box (jP ) @ (0, 12) + Signature: 0d0a870a + File Type Box (ftyp) @ (12, 20) + Brand: jp2 + Compatibility: ['jp2 '] + JP2 Header Box (jp2h) @ (32, 45) + Image Header Box (ihdr) @ (40, 22) + Size: [1456 2592 3] + Bitdepth: 8 + Signed: False + Compression: wavelet + Colorspace Unknown: False + Colour Specification Box (colr) @ (62, 15) + Method: enumerated colorspace + Precedence: 0 + Colorspace: sRGB + UUID Box (uuid) @ (77, 3146) + UUID: be7acfcb-97a9-42e8-9c71-999491e3afac (XMP) + UUID Data: + + + + Google + 2013-02-09T14:47:53 + + + 1 + 72/1 + 72/1 + 2 + HTC + HTC Glacier + 2592 + 1456 + + + 8 + 8 + 8 + + + 2 + 3 + + + 1343036288/4294967295 + 1413044224/4294967295 + + + + + 2748779008/4294967295 + 1417339264/4294967295 + 1288490240/4294967295 + 2576980480/4294967295 + 644245120/4294967295 + 257698032/4294967295 + + + + + 1 + 2528 + 1424 + 353/100 + 0 + 0/1 + WGS-84 + 2013-02-09T14:47:53 + + + 76 + + + 0220 + 0100 + + + 1 + 2 + 3 + 0 + + + 42,20.56N + 71,5.29W + 2013-02-09T19:47:53Z + NETWORK + + + 2013-02-09T14:47:53 + + + + + Glymur + Python XMP Toolkit + + + + + + + Contiguous Codestream Box (jp2c) @ (3223, 1132296) + Main header: + SOC marker segment @ (3231, 0) + SIZ marker segment @ (3233, 47) + Profile: 2 + Reference 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)) + COD marker segment @ (3282, 12) + Coding style: + Entropy coder, without partitions + SOP marker segments: False + EPH marker segments: False + Coding style parameters: + Progression order: LRCP + Number of layers: 2 + Multiple component transformation usage: reversible + Number of resolutions: 2 + Code block height, width: (64 x 64) + Wavelet transform: 5-3 reversible + Precinct size: default, 2^15 x 2^15 + Code block context: + Selective arithmetic coding bypass: False + Reset context probabilities on coding pass boundaries: False + Termination on each coding pass: False + Vertically stripe causal context: False + Predictable termination: False + Segmentation symbols: False + QCD marker segment @ (3296, 7) + Quantization style: no quantization, 2 guard bits + Step size: [(0, 8), (0, 9), (0, 9), (0, 10)] + CME marker segment @ (3305, 37) + "Created by OpenJPEG version 2.0.0" + +That's fairly overwhelming, and perhaps lost in the flood of information +is the fact that the codestream metadata is limited to just what's in the +main codestream header. You can suppress the codestream and XML details by +making use of the :py:meth:`set_printoptions` function:: -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. :: + >>> glymur.set_printoptions(codestream=False, xml=False) + >>> print(jp2) + File: nemo.jp2 + JPEG 2000 Signature Box (jP ) @ (0, 12) + Signature: 0d0a870a + File Type Box (ftyp) @ (12, 20) + Brand: jp2 + Compatibility: ['jp2 '] + JP2 Header Box (jp2h) @ (32, 45) + Image Header Box (ihdr) @ (40, 22) + Size: [1456 2592 3] + Bitdepth: 8 + Signed: False + Compression: wavelet + Colorspace Unknown: False + Colour Specification Box (colr) @ (62, 15) + Method: enumerated colorspace + Precedence: 0 + Colorspace: sRGB + UUID Box (uuid) @ (77, 3146) + UUID: be7acfcb-97a9-42e8-9c71-999491e3afac (XMP) + Contiguous Codestream Box (jp2c) @ (3223, 1132296) - >>> print(j.get_codestream()) +It is possible to print all the gory codestream details as well, i.e. :: + + >>> print(j.get_codestream()) # details not shown ... add XML metadata? ===================== @@ -55,7 +222,7 @@ Consider the following XML file `data.xml` : :: -The **append** method can add an XML box as shown below:: +The :py:meth:`append` method can add an XML box as shown below:: >>> import shutil >>> import glymur @@ -74,6 +241,7 @@ codestream provided by `goodstuff.j2k` (a file consisting of a raw codestream), you can use the :py:meth:`wrap` method with no box argument: :: >>> import glymur + >>> glymur.set_printoptions(codestream=False) >>> jfile = glymur.data.goodstuff() >>> j2k = glymur.Jp2k(jfile) >>> jp2 = j2k.wrap("newfile.jp2") @@ -96,10 +264,6 @@ you can use the :py:meth:`wrap` method with no box argument: :: Precedence: 0 Colorspace: sRGB Contiguous Codestream Box (jp2c) @ (77, 115228) - Main header: - . - . (truncated) - . 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 @@ -146,12 +310,7 @@ the following will work. :: Light Ale - Contiguous Codestream Box (jp2c) @ (153, 115236) - Main header: - . - . (truncated) - . As to the question of which method you should use, :py:meth:`append` or :py:meth:`wrap`, to add metadata, you should keep in mind that :py:meth:`wrap`