forked from openpreserve/jpylyzer
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathuserManual.html
3190 lines (3188 loc) · 172 KB
/
userManual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
layout: page
title: User Manual
---
{% include JB/setup %}
<header>
<h1 class="title">Jpylyzer User Manual</h1>
<p class="author"></p>
</header>
<nav id="TOC">
<ul>
<li><a href="#introduction"><span class="toc-section-number">1</span> Introduction</a><ul>
<li><a href="#about-jpylyzer"><span class="toc-section-number">1.1</span> About jpylyzer</a></li>
<li><a href="#validation-scope-and-restrictions"><span class="toc-section-number">1.2</span> Validation: scope and restrictions</a></li>
<li><a href="#outline"><span class="toc-section-number">1.3</span> Outline of this User Manual</a></li>
<li><a href="#funding"><span class="toc-section-number">1.4</span> Funding</a></li>
<li><a href="#license"><span class="toc-section-number">1.5</span> License</a></li>
</ul></li>
<li><a href="#installation"><span class="toc-section-number">2</span> Installation and set-up</a><ul>
<li><a href="#obtaining-the-software"><span class="toc-section-number">2.1</span> Obtaining the software</a></li>
<li><a href="#installation-pip"><span class="toc-section-number">2.2</span> Installation with Pip (Linux/Unix, Windows, Mac OS X)</a></li>
<li><a href="#installation-windows"><span class="toc-section-number">2.3</span> Installation of Windows binaries (Windows only)</a></li>
<li><a href="#installation-debian"><span class="toc-section-number">2.4</span> Installation of Debian packages (Ubuntu/Linux)</a></li>
</ul></li>
<li><a href="#using-jpylyzer"><span class="toc-section-number">3</span> Using <em>jpylyzer</em></a><ul>
<li><a href="#using-overview"><span class="toc-section-number">3.1</span> Overview</a></li>
<li><a href="#command-line-usage"><span class="toc-section-number">3.2</span> Command-line usage</a></li>
<li><a href="#using-as-python-module"><span class="toc-section-number">3.3</span> Using <em>jpylyzer</em> as a Python module</a></li>
</ul></li>
<li><a href="#structure-jp2"><span class="toc-section-number">4</span> Structure of a JP2 file</a><ul>
<li><a href="#structure-scope"><span class="toc-section-number">4.1</span> Scope of this chapter</a></li>
<li><a href="#general-format-structure"><span class="toc-section-number">4.2</span> General format structure</a></li>
<li><a href="#general-box-structure"><span class="toc-section-number">4.3</span> General structure of a box</a></li>
<li><a href="#defined-boxes"><span class="toc-section-number">4.4</span> Defined boxes in JP2</a></li>
</ul></li>
<li><a href="#output-format"><span class="toc-section-number">5</span> Output format</a><ul>
<li><a href="#output-format-overview"><span class="toc-section-number">5.1</span> Overview</a></li>
<li><a href="#toolinfo-element"><span class="toc-section-number">5.2</span> toolInfo element</a></li>
<li><a href="#file-element"><span class="toc-section-number">5.3</span> file element</a></li>
<li><a href="#fileinfo-element"><span class="toc-section-number">5.4</span> fileInfo element</a></li>
<li><a href="#statusinfo-element"><span class="toc-section-number">5.5</span> statusInfo element</a></li>
<li><a href="#isvalid-element"><span class="toc-section-number">5.6</span> isValid element</a></li>
<li><a href="#tests-element"><span class="toc-section-number">5.7</span> tests element</a></li>
<li><a href="#properties-element"><span class="toc-section-number">5.8</span> properties element</a></li>
<li><a href="#propertiesExtension-element"><span class="toc-section-number">5.9</span> propertiesExtension element</a></li>
</ul></li>
<li><a href="#jp2-box-by-box"><span class="toc-section-number">6</span> JP2: box by box</a><ul>
<li><a href="#about-properties-tests-trees"><span class="toc-section-number">6.1</span> About the properties and tests trees</a></li>
<li><a href="#jpeg2000-signature-box"><span class="toc-section-number">6.2</span> JPEG 2000 Signature box</a></li>
<li><a href="#file-type-box"><span class="toc-section-number">6.3</span> File Type box</a></li>
<li><a href="#jp2-header-box"><span class="toc-section-number">6.4</span> JP2 Header box (superbox)</a></li>
<li><a href="#image-header-box"><span class="toc-section-number">6.5</span> Image Header box (child of JP2 Header box)</a></li>
<li><a href="#bits-per-component-box"><span class="toc-section-number">6.6</span> Bits Per Component box (child of JP2 Header box)</a></li>
<li><a href="#colour-specification-box"><span class="toc-section-number">6.7</span> Colour Specification box (child of JP2 Header box)</a></li>
<li><a href="#palette-box"><span class="toc-section-number">6.8</span> Palette box (child of JP2 Header box)</a></li>
<li><a href="#component-mapping-box"><span class="toc-section-number">6.9</span> Component Mapping box (child of JP2 Header box)</a></li>
<li><a href="#channel-definition-box"><span class="toc-section-number">6.10</span> Channel Definition box (child of JP2 Header box)</a></li>
<li><a href="#resolution-box"><span class="toc-section-number">6.11</span> Resolution box (child of JP2 Header box, superbox)</a></li>
<li><a href="#capture-resolution-box"><span class="toc-section-number">6.12</span> Capture Resolution box (child of Resolution box)</a></li>
<li><a href="#display-resolution-box"><span class="toc-section-number">6.13</span> Default Display Resolution box (child of Resolution box)</a></li>
<li><a href="#codestream-box"><span class="toc-section-number">6.14</span> Contiguous Codestream box</a></li>
<li><a href="#intellectual-property-box"><span class="toc-section-number">6.15</span> Intellectual Property box</a></li>
<li><a href="#xml-box"><span class="toc-section-number">6.16</span> XML box</a></li>
<li><a href="#uuid-box"><span class="toc-section-number">6.17</span> UUID box</a></li>
<li><a href="#uuid-info-box"><span class="toc-section-number">6.18</span> UUID Info box (superbox)</a></li>
<li><a href="#uuid-list-box"><span class="toc-section-number">6.19</span> UUID List box (child of UUID Info box)</a></li>
<li><a href="#data-entry-url-box"><span class="toc-section-number">6.20</span> Data Entry URL box (child of UUID Info box)</a></li>
<li><a href="#unknown-box-section"><span class="toc-section-number">6.21</span> Unknown box</a></li>
<li><a href="#top-level-tests-properties"><span class="toc-section-number">6.22</span> Top-level tests and properties</a></li>
</ul></li>
<li><a href="#contiguous-codestream-box-chapter"><span class="toc-section-number">7</span> Contiguous Codestream box</a><ul>
<li><a href="#codestream-structure"><span class="toc-section-number">7.1</span> General codestream structure</a></li>
<li><a href="#limitations-codestream-validation"><span class="toc-section-number">7.2</span> Limitations of codestream validation</a></li>
<li><a href="#structure-reported-output"><span class="toc-section-number">7.3</span> Structure of reported output</a></li>
<li><a href="#contiguous-codestream-box"><span class="toc-section-number">7.4</span> Contiguous Codestream box</a></li>
<li><a href="#siz-marker"><span class="toc-section-number">7.5</span> Image and tile size (SIZ) marker segment (child of Contiguous Codestream box)</a></li>
<li><a href="#cod-marker"><span class="toc-section-number">7.6</span> Coding style default (COD) marker segment</a></li>
<li><a href="#coc-marker"><span class="toc-section-number">7.7</span> Coding style component (COC) marker segment</a></li>
<li><a href="#rgn-marker"><span class="toc-section-number">7.8</span> Region-of-interest (RGN) marker segment</a></li>
<li><a href="#qcd-marker"><span class="toc-section-number">7.9</span> Quantization default (QCD) marker segment</a></li>
<li><a href="#qcc-marker"><span class="toc-section-number">7.10</span> Quantization component (QCC) marker segment</a></li>
<li><a href="#poc-marker"><span class="toc-section-number">7.11</span> Progression order change (POC) marker segment</a></li>
<li><a href="#crg-marker"><span class="toc-section-number">7.12</span> Component registration (CRG) marker segment</a></li>
<li><a href="#com-marker"><span class="toc-section-number">7.13</span> Comment (COM) marker segment</a></li>
<li><a href="#tile-part"><span class="toc-section-number">7.14</span> Tile part (child of Contiguous Codestream box)</a></li>
<li><a href="#sot-marker"><span class="toc-section-number">7.15</span> Start of tile part (SOT) marker segment (child of tile part)</a></li>
<li><a href="#plm-marker"><span class="toc-section-number">7.16</span> Packet length, main header (PLM) marker segment</a></li>
<li><a href="#ppm-marker"><span class="toc-section-number">7.17</span> Packed packet headers, main header (PPM) marker segment</a></li>
<li><a href="#tlm-marker"><span class="toc-section-number">7.18</span> Tile-part lengths (TLM) marker segment</a></li>
<li><a href="#plt-marker"><span class="toc-section-number">7.19</span> Packet length, tile-part header (PLT) marker segment</a></li>
<li><a href="#ppt-marker"><span class="toc-section-number">7.20</span> Packed packet headers, tile-part header (PPT) marker segment</a></li>
</ul></li>
<li><a href="#references"><span class="toc-section-number">8</span> References</a></li>
</ul>
</nav>
<h1 id="introduction"><span class="header-section-number">1</span> Introduction</h1>
<h2 id="about-jpylyzer"><span class="header-section-number">1.1</span> About jpylyzer</h2>
<p>This User Manual documents <em>jpylyzer</em>, a validator and feature extractor for JP2 images. JP2 is the still image format that is defined by JPEG 2000 Part 1 (ISO/IEC 15444-1). <em>Jpylyzer</em> was specifically created to answer the following questions that you might have about any JP2 file:</p>
<ol type="1">
<li><p>Is this really a JP2 and does it really conform to the format’s specifications (validation)?</p></li>
<li><p>What are the technical characteristics of this image (feature extraction)?</p></li>
</ol>
<h2 id="validation-scope-and-restrictions"><span class="header-section-number">1.2</span> Validation: scope and restrictions</h2>
<p>Since the word ‘validation’ means different things to different people, a few words about the overall scope of <em>jpylyzer</em>. First of all, it is important to stress that <em>jpylyzer</em> is not a ‘one stop solution’ that will tell you that an image is 100% perfect. What <em>jpylyzer</em> does is this: based on the JP2 format specification (ISO/IEC 15444-1), it parses a file. It then subjects the file’s contents to a large number of tests, each of which is based on the requirements and restrictions that are defined by the standard. If a file fails one or more tests, this implies that it does not conform to the standard, and is no valid JP2. Importantly, this presumes that <em>jpylyzer</em>’s tests accurately reflect the format specification, without producing false positives.</p>
<h3 id="valid-means-probably-valid"><span class="header-section-number">1.2.1</span> ‘Valid’ means ‘probably valid’</h3>
<p>If a file passes all tests, this is an indication that it is <em>probably</em> valid JP2. This (intentionally) implies a certain degree of remaining uncertainty, which is related to the following.</p>
<p>First of all, <em>jpylyzer</em> (or any other format validator for that matter) ‘validates’ a file by trying to prove that it does <em>not</em> conform to the standard. It cannot prove that that a file <em>does</em> conform to the standard.</p>
<p>Related to this, even though <em>jpylyzer</em>’s validation process is very comprehensive, it is not complete. For instance, the validation of JPEG 2000 codestreams at this moment is still somewhat limited. <a href="#limitations-codestream-validation">Section 7.2</a> discusses these limitations in detail. Some of these limitations ( e.g. optional codestream segment markers that are only minimally supported at this stage) may be taken away in upcoming versions of the tool.</p>
<h3 id="no-check-on-compressed-bitstreams"><span class="header-section-number">1.2.2</span> No check on compressed bitstreams</h3>
<p>One important limitation that most certainly will <em>not</em> be addressed in any upcoming versions is that <em>jpylyzer</em> does not analyse the data in the compressed bitstream segments. Doing so would involve decoding the whole image, and this is completely out of <em>jpylyzer</em>’s scope. As a result, it is possible that a JP2 that passes each of <em>jpylyzer</em>’s tests will nevertheless fail to render correctly in a viewer application.</p>
<h3 id="recommendations-for-use-in-quality-assurance-workflows"><span class="header-section-number">1.2.3</span> Recommendations for use in quality assurance workflows</h3>
<p>Because of the foregoing, a thorough JP2 quality assurance workflow should not rely on <em>jpylyzer</em> (or any other format validator) alone, but it should include other tests as well. Some obvious examples are:</p>
<ul>
<li><p>A rendering test that checks if a file renders at all</p></li>
<li><p>Format migration workflows (e.g. TIFF to JP2) should ideally also include some comparison between source and destination images (e.g. a pixel-wise comparison)</p></li>
</ul>
<p>Conversely, an image that successfully passes a rendering test or pixel-wise comparison may still contain problematic features ( e.g. incorrect colour space information), so validation, rendering tests and pixel-wise comparisons are really complementary to each other.</p>
<h3 id="note-on-icc-profile-support"><span class="header-section-number">1.2.4</span> Note on ICC profile support</h3>
<p>The support of ICC profiles in JP2 was recently extended through an <a href="http://www.itu.int/rec/T-REC-T.800-201303-P!Amd6/en">amendment</a> to the standard. These changes are taken into account by <em>jpylyzer</em>, which is in line with the most recent version of the (updated) standard.</p>
<h2 id="outline"><span class="header-section-number">1.3</span> Outline of this User Manual</h2>
<p><a href="#installation">Chapter 2</a> describes the installation process of <em>jpylyzer</em> for Windows and Unix-based systems. <a href="#using-jpylyzer">Chapter 3</a> explains the usage of <em>jpylyzer</em> as a command-line tool, or as an importable Python module. <a href="#structure-jp2">Chapter 4</a> gives a brief overview of the structure of JP2 and its ‘box’ structure. <em>Jpylyzer</em>’s output format is explained in <a href="#output-format">chapter 5</a>. The final chapters give a detailed description of the tests that <em>jpylyzer</em> performs for validation, and its reported properties. <a href="#jp2-box-by-box">Chapter 6</a> does this for all ‘boxes’, except for the ‘Contiguous Codestream’ box, which is given a <a href="#contiguous-codestream-box-chapter">Chapter (7)</a> of its own.</p>
<h2 id="funding"><span class="header-section-number">1.4</span> Funding</h2>
<p>The development of <em>jpylyzer</em> was funded by the EU FP 7 project SCAPE (SCAlable Preservation Environments). More information about this project can be found here:</p>
<p><a href="http://www.scape-project.eu/" class="uri">http://www.scape-project.eu/</a></p>
<h2 id="license"><span class="header-section-number">1.5</span> License</h2>
<p><em>Jpylyzer</em> is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see:</p>
<p><a href="http://www.gnu.org/licenses/" class="uri">http://www.gnu.org/licenses/</a></p>
<p>On Debian systems, the complete text of the GNU Lesser General Public License version 3 can be found in:</p>
<pre><code>/usr/share/common-licenses/LGPL-3</code></pre>
<h1 id="installation"><span class="header-section-number">2</span> Installation and set-up</h1>
<h2 id="obtaining-the-software"><span class="header-section-number">2.1</span> Obtaining the software</h2>
<p>To obtain the latest version of the software please use the download links at the <em>jpylyzer</em> homepage:</p>
<p><a href="http://jpylyzer.openpreservation.org/" class="uri">http://jpylyzer.openpreservation.org/</a></p>
<p>You have three options:</p>
<ol type="1">
<li><p>Install the software with the <em>Pip</em> package manager. This works on all platforms (Windows, Linux, Mac, etc.), but you need to have the Python interpreter available on your system. Jpylyzer is compatible with Python 2.7, and Python 3.2 and more recent (Python 3.0 and 3.1 are not supported).</p></li>
<li><p>Alternatively, for Windows users there is also a set of stand-alone binaries<a href="#fn1" class="footnote-ref" id="fnref1"><sup>1</sup></a>. These allow you to run <em>jpylyzer</em> as an executable Windows application, without any need for installing Python. This option is particularly useful for Windows users who cannot (or don’t want to) install software on their system.</p></li>
<li><p>For Linux users Debian packages are available.</p></li>
</ol>
<p>These options are described in the following sections.</p>
<h2 id="installation-pip"><span class="header-section-number">2.2</span> Installation with Pip (Linux/Unix, Windows, Mac OS X)</h2>
<h3 id="general-installation-procedure"><span class="header-section-number">2.2.1</span> General installation procedure</h3>
<p>First make sure you have a recent version of <em>pip</em>. Then install <em>jpylyzer</em> with the following command:</p>
<pre><code>pip install jpylyzer</code></pre>
<h3 id="single-user-installation-linux"><span class="header-section-number">2.2.2</span> Single user installation (Linux)</h3>
<p>On most Linux systems the above command needs to be run as super user (see below). If you don’t want this use the below command for a single-user install:</p>
<pre><code>pip install jpylyzer --user</code></pre>
<p>This will install the software to the <code>.local</code> folder (hidden by default!) in your home directory (<code>~/.local</code>). Next try to run <em>jpylyzer</em> by entering:</p>
<pre><code>jpylyzer</code></pre>
<p>Most likely this will result in:</p>
<pre><code>jpylyzer: command not found</code></pre>
<p>If this happens, add the directory <code>~/.local/bin</code> (which is where the jpylyzer command-line tool is installed) to the <code>PATH</code> environment variable (you only need to do this once). To do this, locate the (hidden) file <code>.profile</code> in you home directory (<code>~/</code>), and open it in a text editor. Then add the following lines at the end of the file:</p>
<pre><code># set PATH so it includes the user's .local bin if it exists
if [ -d "$HOME/.local/bin" ] ; then
PATH="$HOME/.local/bin:$PATH"
fi</code></pre>
<p>Save the file, log out of your session and then log in again. Open a command terminal and type:</p>
<pre><code>jpylyzer</code></pre>
<p>If all went well you now see this:</p>
<pre><code>usage: jpylyzer [-h] [--format FMT] [--legacyout] [--mix {1,2}] [--nopretty]
[--nullxml] [--recurse] [--verbose] [--version] [--wrapper]
jp2In [jp2In ...]
jpylyzer: error: the following arguments are required: jp2In</code></pre>
<p>Which means that the installation was successful!</p>
<h3 id="global-installation-linux"><span class="header-section-number">2.2.3</span> Global installation (Linux)</h3>
<p>Simply enter:</p>
<pre><code>sudo -H pip install isolyzer</code></pre>
<p>No further configuration is needed in this case.</p>
<h3 id="note-on-pre-releases"><span class="header-section-number">2.2.4</span> Note on pre-releases</h3>
<p>The above command lines will only install stable versions of jpylyzer. In order to install the latest pre-release, add the <code>--pre</code> switch. For example:</p>
<pre><code>sudo -H pip install jpylyzer --pre</code></pre>
<h2 id="installation-windows"><span class="header-section-number">2.3</span> Installation of Windows binaries (Windows only)</h2>
<p>Download the binary using the link on the <em>jpylyzer</em> homepage. Unzip the contents of this file to an empty folder on your PC. <em>Jpylyzer</em> should now be ready for use.</p>
<h3 id="testing-the-installation"><span class="header-section-number">2.3.1</span> Testing the installation</h3>
<p>To test your installation, open a Command Prompt (‘DOS prompt’) and type:</p>
<pre><code>%jpylyzerPath%\jpylyzer</code></pre>
<p>In the above command, replace <em>%jpylyzerPath%</em> with the full path to the <em>jpylyzer</em> installation directory (i.e. the directory that contains ‘jpylyzer.exe’ and its associated files). For example, if you extracted the files to directory <code>c:\tools\jpylyzer</code>, the command would become:</p>
<pre><code>c:\tools\jpylyzer\jpylyzer</code></pre>
<p>Executing this command should result in the following screen output:</p>
<pre><code>usage: jpylyzer [-h] [--format FMT] [--legacyout] [--mix {1,2}] [--nopretty]
[--nullxml] [--recurse] [--verbose] [--version] [--wrapper]
jp2In [jp2In ...]
jpylyzer: error: the following arguments are required: jp2In</code></pre>
<h3 id="running-jpylyzer-without-typing-the-full-path"><span class="header-section-number">2.3.2</span> Running jpylyzer without typing the full path</h3>
<p>Optionally, you may also want to add the full path of the <em>jpylyzer</em> installation directory to the Windows ’Path’ environment variable. Doing so allows you to run <em>jpylyzer</em> from any directory on your PC without having to type the full path. In Windows 7 you can do this by selecting ‘settings’ from the ‘Start’ menu; then go to ‘control panel’/’system’ and go to the ‘advanced’ tab. Click on the ‘environment variables’ button. Finally, locate the ‘Path’ variable in the ‘system variables’ window, click on ‘Edit’ and add the full <em>jpylyzer</em> path (this requires local Administrator privileges). The settings take effect on any newly opened command prompt.</p>
<h2 id="installation-debian"><span class="header-section-number">2.4</span> Installation of Debian packages (Ubuntu/Linux)</h2>
<p>For Linux, Debian packages of <em>jpylyzer</em> exist. To install, simply download the <em>.deb</em> file, double-click on it and select <em>Install Package</em>. Alternatively you can also do this in the command terminal by typing:</p>
<pre><code>sudo dpkg -i opf-jpylyzer_2.0.0_all.deb</code></pre>
<p>In both cases you need to have administrative privileges.</p>
<p>For <em>Ubuntu</em> and <em>Debian</em> alternative packages are available in the official release channels. To install simply run the following commands:</p>
<pre><code>sudo apt-get update
sudo apt-get install python-jpylyzer</code></pre>
<h1 id="using-jpylyzer"><span class="header-section-number">3</span> Using <em>jpylyzer</em></h1>
<h2 id="using-overview"><span class="header-section-number">3.1</span> Overview</h2>
<p>This chapter describes the general use of <em>jpylyzer</em>. The first sections cover the use of <em>jpylyzer</em> as a command-line tool and as an importable Python module.</p>
<h2 id="command-line-usage"><span class="header-section-number">3.2</span> Command-line usage</h2>
<p>This section explains <em>jpylyzer</em>’s general command-line interface. For the sake of brevity, full paths to <em>jpylyzer</em> are omitted. This means that, depending on your system and settings, you may have to substitute each occurrence of ‘jpylyzer’ with its full path, the corresponding Windows binary, or a combination of both. The following examples illustrate this:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">This User Manual</th>
<th style="text-align: left;">jpylyzer</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Substitution example Linux</td>
<td style="text-align: left;"><code>/home/jpylyzer/jpylyzer</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">Substitution example Windows binaries</td>
<td style="text-align: left;"><code>c:\tools\jpylyzer\jpylyzer</code></td>
</tr>
</tbody>
</table>
<p>Furthermore, command line arguments that are given between square brackets (example: <code>[-h]</code>) are optional.</p>
<h3 id="synopsis"><span class="header-section-number">3.2.1</span> Synopsis</h3>
<p><em>Jpylyzer</em> can be invoked using the following command-line arguments:</p>
<pre><code>usage: jpylyzer [-h] [--format FMT] [--legacyout] [--mix {1,2}] [--nopretty]
[--nullxml] [--recurse] [--verbose] [--version] [--wrapper]
jp2In [jp2In ...]</code></pre>
<h4 id="positional-arguments"><span class="header-section-number">3.2.1.1</span> Positional arguments</h4>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Argument</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>jp2In</code></td>
<td style="text-align: left;">input JP2 image(s), may be one or more (whitespace-separated) path expressions; prefix wildcard (*) with backslash (\) in Linux</td>
</tr>
</tbody>
</table>
<h4 id="optional-arguments"><span class="header-section-number">3.2.1.2</span> Optional arguments</h4>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Argument</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>[-h, --help]</code></td>
<td style="text-align: left;">show help message and exit</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>[--format FMT]</code></td>
<td style="text-align: left;">validation format; allowed values are <code>jp2</code> (used by default) and <code>j2c</code> (which activates raw codestream validation)</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>[--mix {1,2}]</code></td>
<td style="text-align: left;">report additional output in NISO MIX format (version 1.0 or 2.0)</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>[--legacyout]</code></td>
<td style="text-align: left;">report output in jpylyzer 1.x format (provided for backward compatibility only)</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>[--nopretty]</code></td>
<td style="text-align: left;">suppress pretty-printing of XML output</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>[--nullxml]</code></td>
<td style="text-align: left;">extract null-terminated XML content from XML and UUID boxes(doesn’t affect validation)</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>[--recurse, -r]</code></td>
<td style="text-align: left;">when analysing a directory, recurse into subdirectories (implies <code>--wrapper</code> if <code>--legacyout</code> is used)</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>[--verbose]</code></td>
<td style="text-align: left;">report test results in verbose format</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>[-v, --version]</code></td>
<td style="text-align: left;">show program’s version number and exit</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>[--wrapper, -w]</code></td>
<td style="text-align: left;">wrap output for individual image(s) in ‘results’ XML element (deprecated from jpylyzer 2.x onward, only takes effect if <code>--legacyout</code> is used)</td>
</tr>
</tbody>
</table>
<p>Note that the input can either be a single image, a space-separated sequence of images, a pathname expression that includes multiple images, or any combination of the above. For example, the following command will process one single image:</p>
<pre><code>jpylyzer rubbish.jp2</code></pre>
<p>The next example shows how to process all files with a ‘jp2’ extension in the current directory:</p>
<pre><code>jpylyzer *.jp2</code></pre>
<p>Note that on Unix/Linux based systems pathname expressions may not work properly unless you wrap them in quotation marks:</p>
<pre><code>jpylyzer "*.jp2"</code></pre>
<h3 id="output-redirection"><span class="header-section-number">3.2.2</span> Output redirection</h3>
<p>All output (except warning and system error messages) is directed to the standard output device (stdout). By default this is the console screen. Use your platform’s standard output redirection operators to redirect output to a file. The most common situation will be to redirect the output of one invocation of <em>jpylyzer</em> to an XML file, which can be done with the ‘>’ operator (both under Windows and Linux):</p>
<pre><code>jpylyzer jp2In > outputFile</code></pre>
<p>E.g. the following command will run <em>jpylyzer</em> on image ‘rubbish.jp2’ and redirects the output to file ‘rubbish.xml’:</p>
<pre><code>jpylyzer rubbish.jp2 > rubbish.xml</code></pre>
<p>The format of the XML output is described in <a href="#output-format">Chapter 5</a>.</p>
<h3 id="format-option"><span class="header-section-number">3.2.3</span> ‘format’ option</h3>
<p>By default, <em>jpylyzer</em> validates against the <em>JP2</em> format specification. Starting with version 2.0, <em>jpylyzer</em> can also validate raw JPEG 2000 codestreams that are not wrapped inside a <em>JP2</em> container. For codestream validation, use the <code>--format</code> option with value <code>j2c</code>, e.g.:</p>
<pre><code>jpylyzer --format j2c rubbish.j2c > rubbish.xml</code></pre>
<h3 id="mix-option"><span class="header-section-number">3.2.4</span> ‘mix’ option</h3>
<p>When this option is used, <em>jpylyzer</em> reports additional output in <a href="http://www.loc.gov/standards/mix/"><em>NISO MIX</em></a> format. This option takes one argument that defines whether <em>MIX</em> 1.0 or <em>MIX</em> 2.0 is used. For example, the following command will result in <em>MIX</em> 2.0 output:</p>
<pre><code>jpylyzer --mix 2 rubbish.jp2 > rubbish.xml</code></pre>
<p>The <em>MIX</em> output is wrapped inside a <em>file/propertiesExtension</em> element. Note that <em>MIX</em> output is <em>only</em> written for files that are valid JP2 (files that are not valid result in an empty <em>propertiesExtension</em> element). Also, the <code>--mix</code> option is ignored if <code>--format</code> is set to <code>j2c</code>, or if <code>--legacyout</code> (see below) is used.</p>
<h3 id="legacyout-option"><span class="header-section-number">3.2.5</span> ‘legacyout’ option</h3>
<p>The output format of <em>jpylyzer</em> has changed in version 2.0, which may break existing workflows that expect output in 1.x format. For backward compatibility the <code>--legacyout</code> option results in output that follows the old 1.x format. Note that codestream validation is disabled if you use this option.</p>
<h3 id="recurse-option"><span class="header-section-number">3.2.6</span> ‘recurse’ option</h3>
<p>If the <code>--recurse</code> option is used, <em>jpylyzer</em> will recursively traverse all subdirectories of a filepath expression. E.g:</p>
<pre><code>jpylyzer /home/myJP2s/*.jp2 > rubbish.xml</code></pre>
<p>In this case <em>jpylyzer</em> analyses all files that have a <em>.jp2</em> extension in directory <em>/home/myJP2s</em> and all its subdirectories.</p>
<h3 id="wrapper-option-deprecated"><span class="header-section-number">3.2.7</span> ‘wrapper’ option (deprecated)</h3>
<p>This deprecated option is included for backward-compatibility, and only takes effect if <code>--legacyout</code> (see above) is used.By default, the <em>jpylyzer</em> 1.x releases would create a separate XML tree for each analysed image, without any overarching hierarchy. For multiple-image pathname expressions this resulted in output that was <strong>not</strong> well-formed XML. The <code>--legacyout</code> option still results in this is behaviour. For example:</p>
<pre><code>jpylyzer --legacyout rubbish.jp2 garbage.jp2 > rubbish.xml</code></pre>
<p>In this case, the file ‘rubbish.xml’ contains a succession of two XML trees, which by itself is not well-formed XML. The <code>--wrapper</code> option is provided to create valid XML instead:</p>
<pre><code>jpylyzer --legacyout --wrapper rubbish.jp2 garbage.jp2 > rubbish.xml</code></pre>
<p>In the above case the XML trees of the individual images are wrapped inside a ‘results’ element. When the <code>--recurse</code> option is used, jpylyzer will automatically wrap the output in a ‘results’ element, so there’s no need to specify <code>--wrapper</code> in that case.</p>
<p>Starting with version 2.0, <em>jpylyzer</em> <em>always</em> generates well-formed XML (unless the <code>--legacyout</code> option is used), which makes the <code>--wrapper</code> option largely obsolete, apart from cases where the ‘old’ behaviour is needed for backward-compatibility reasons.</p>
<h3 id="nullxml-option"><span class="header-section-number">3.2.8</span> ‘nullxml’ option</h3>
<p>The <em>nullxml</em> option was added to enable extraction of XML content that is terminated by a null-byte. By default <em>jpylyzer</em> doesn’t report the XML in that case, because it throws an exception in the XML parser. Apparently some old versions of the Kakadu demo applications would erroneously add a null-byte to embedded XML, so this option can be used to force extraction for images that are affected by this.</p>
<h3 id="user-warnings"><span class="header-section-number">3.2.9</span> User warnings</h3>
<p>Under the following conditions <em>jpylyzer</em> will print a user warning to the standard error device (typically the console screen):</p>
<h4 id="no-images-to-check"><span class="header-section-number">3.2.9.1</span> No images to check</h4>
<p>If there are no input images to check (typically because the value of jp2In refers to a non-existent file), the following warning message is shown:</p>
<pre><code>User warning: no images to check!</code></pre>
<h4 id="unsupported-box"><span class="header-section-number">3.2.9.2</span> Unsupported box</h4>
<p>In some cases you will see the following warning message:</p>
<pre><code>User warning: ignoring 'boxName' (validator function not yet implemented)</code></pre>
<p>The reason for this: a JP2 file is made up of units that are called ‘boxes’. This is explained in more detail in <a href="#structure-jp2">Chapter 4</a>. Each ‘box’ has its own dedicated validator function. At this stage validator functions are still missing for a small number of (optional) boxes. <em>Jpylyzer</em> will display the above warning message if it encounters a (yet) unsupported box. Any unsupported boxes are simply ignored, and the remainder of the file will be analyzed (and validated) normally.</p>
<h4 id="error-while-processing-a-file"><span class="header-section-number">3.2.9.3</span> Error while processing a file</h4>
<p>In rare cases you may come across one of the following messages:</p>
<pre><code>User warning: memory error (file size too large)</code></pre>
<p>Memory errors may occur for (very) large images. If you get this warning, try using a machine with more RAM. Also, a machine’s chip architecture and the operating system may put constraints on the amount of memory that can be allocated.</p>
<p>The following warning indicates an input error:</p>
<pre><code>User warning: I/O error (cannot open file)</code></pre>
<p>Finally, the following messages most likely indicate a jpylyzer bug:</p>
<pre><code>User warning:runtime error (please report to developers)
User warning: unknown error (please report to developers)</code></pre>
<p>If you ever run into either of these two errors, please get in touch with the jpylyzer developers. The easiest way to do this is to create a new issue at:</p>
<p><a href="https://github.com/openpreserve/jpylyzer/issues" class="uri">https://github.com/openpreserve/jpylyzer/issues</a></p>
<h4 id="unknown-box"><span class="header-section-number">3.2.9.4</span> Unknown box</h4>
<p>Occasionally, you may see this warning message:</p>
<pre><code>User warning: ignoring unknown box</code></pre>
<p>This happens if <em>jpylyzer</em> encounters a box that is not defined by JPEG 2000 Part 1. It should be noted that, to a large extent, JPEG 2000 Part 1 permits the presence of boxes that are defined outside the standard. Again, <em>jpylyzer</em> will simply ignore these and process all other boxes normally.</p>
<h2 id="using-as-python-module"><span class="header-section-number">3.3</span> Using <em>jpylyzer</em> as a Python module</h2>
<p>Instead of using <em>jpylyzer</em> from the command-line, you can also import it as a module in your own Python programs. To do so, install jpylyzer with <em>pip</em>. Then import <em>jpylyzer</em> into your code by adding:</p>
<div class="sourceCode" id="cb33"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb33-1" data-line-number="1"><span class="im">from</span> jpylyzer <span class="im">import</span> jpylyzer</a></code></pre></div>
<p>Subsequently you can call any function that is defined in <em>jpylyzer.py</em>. In practice you will most likely only need the <em>checkOneFile</em> function. The following minimal script shows how this works:</p>
<div class="sourceCode" id="cb34"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb34-1" data-line-number="1"><span class="co">#! /usr/bin/env python</span></a>
<a class="sourceLine" id="cb34-2" data-line-number="2"></a>
<a class="sourceLine" id="cb34-3" data-line-number="3"><span class="im">from</span> jpylyzer <span class="im">import</span> jpylyzer</a>
<a class="sourceLine" id="cb34-4" data-line-number="4"></a>
<a class="sourceLine" id="cb34-5" data-line-number="5"><span class="co"># Define JP2</span></a>
<a class="sourceLine" id="cb34-6" data-line-number="6">myFile <span class="op">=</span> <span class="st">"/home/johan/jpylyzer-test-files/aware.jp2"</span></a>
<a class="sourceLine" id="cb34-7" data-line-number="7"></a>
<a class="sourceLine" id="cb34-8" data-line-number="8"><span class="co"># Analyse with jpylyzer, result to Element object</span></a>
<a class="sourceLine" id="cb34-9" data-line-number="9">myResult <span class="op">=</span> jpylyzer.checkOneFile(myFile)</a>
<a class="sourceLine" id="cb34-10" data-line-number="10"></a>
<a class="sourceLine" id="cb34-11" data-line-number="11"><span class="co"># Return image height value</span></a>
<a class="sourceLine" id="cb34-12" data-line-number="12">imageHeight <span class="op">=</span> myResult.findtext(<span class="st">'./properties/jp2HeaderBox/imageHeaderBox/height'</span>)</a>
<a class="sourceLine" id="cb34-13" data-line-number="13"><span class="bu">print</span>(imageHeight)</a></code></pre></div>
<p>Here, <em>myResult</em> is an <em>Element</em> object that can either be used directly, or converted to XML using the <em>ElementTree</em> module<a href="#fn2" class="footnote-ref" id="fnref2"><sup>2</sup></a>. The structure of the element object follows the XML output that described in <a href="#output-format">Chapter 5</a>.</p>
<p>For validation a raw JPEG 2000 codestreams, call the <em>checkOneFile</em> function with the additional <em>validationFormat</em> argument, and set it to <code>j2c</code>:</p>
<div class="sourceCode" id="cb35"><pre class="sourceCode python"><code class="sourceCode python"><a class="sourceLine" id="cb35-1" data-line-number="1"><span class="co"># Define Codestream</span></a>
<a class="sourceLine" id="cb35-2" data-line-number="2">myFile <span class="op">=</span> <span class="st">"/home/johan/jpylyzer-test-files/rubbish.j2c"</span></a>
<a class="sourceLine" id="cb35-3" data-line-number="3"></a>
<a class="sourceLine" id="cb35-4" data-line-number="4"><span class="co"># Analyse with jpylyzer, result to Element object</span></a>
<a class="sourceLine" id="cb35-5" data-line-number="5">myResult <span class="op">=</span> jpylyzer.checkOneFile(myFile, <span class="st">'j2c'</span>)</a></code></pre></div>
<h1 id="structure-jp2"><span class="header-section-number">4</span> Structure of a JP2 file</h1>
<h2 id="structure-scope"><span class="header-section-number">4.1</span> Scope of this chapter</h2>
<p>This chapter gives a brief overview of the JP2 file format. A basic understanding of the general structure of JP2 is helpful for appreciating how <em>jpylyzer</em> performs its validation. It will also make it easier to understand <em>jpylyzer</em>‘s extracted properties, as these are reported as a hierarchical tree that corresponds to the internal structure of JP2.</p>
<p>For an exhaustive description of every detail of the format you are advised to consult Annex I (‘JP2 file format syntax’) and Annex A (‘Codestream syntax’) of ISO/IEC 15444-1.</p>
<h2 id="general-format-structure"><span class="header-section-number">4.2</span> General format structure</h2>
<p>At the highest level, a JP2 file is made up of a collection of <em>boxes</em>. A <em>box</em> can be thought of as the fundamental building block of the format. Some boxes (‘superboxes’) are containers for other boxes. The Figure below gives an overview of the top-level boxes in a JP2 file.</p>
<figure>
<img src="images/jp2FormatStructure.png" alt="Top-level overview of a JP2 file. Boxes with dashed borders are optional."><figcaption>Top-level overview of a JP2 file. Boxes with dashed borders are optional.</figcaption>
</figure>
<p>A number of things here are noteworthy to point out:</p>
<ul>
<li><p>Some of these boxes are required, whereas others (indicated with dashed lines in the Figure) are optional.</p></li>
<li><p>The order in which the boxes appear in the file is subject to some constraints (e.g. the first box in a JP2 must always be a ‘Signature’ box, followed by a ‘File Type’ box).</p></li>
<li><p>Some boxes may have multiple instances (e.g. ‘Contiguous Codestream’ box), whereas others must be unique (e.g. ‘JP2 Header’ box).</p></li>
</ul>
<p>More specific details can be found in the standard. The important thing here is that requirements like the above are something that should be verified by a validator, and this is exactly what <em>jpylyzer</em> does at the highest level of its validation procedure.</p>
<h2 id="general-box-structure"><span class="header-section-number">4.3</span> General structure of a box</h2>
<p>All boxes are defined by a generic binary structure, which is illustrated by the following Figure:</p>
<figure>
<img src="images/boxStructure.png" alt="General structure of a box."><figcaption>General structure of a box.</figcaption>
</figure>
<p>Most boxes are made up of the following three components:</p>
<ol type="1">
<li><p>A fixed-length ‘box length’ field that indicates the total size of the box (in bytes).</p></li>
<li><p>A fixed-length ‘box type’ field which specifies the type of information that can be found in this box</p></li>
<li><p>The box contents, which contains the actual information within the box. Its internal format depends on the box type. The box contents of a ‘superbox’ will contain its child boxes (which can be parsed recursively).</p></li>
</ol>
<p>In some cases a box will also contain an ‘extended box length field’. This field is needed if the size of a box exceeds 2<sup>32</sup>-1 bytes, which is the maximum value that can be stored in the 4-byte ‘box length’ field.</p>
<h2 id="defined-boxes"><span class="header-section-number">4.4</span> Defined boxes in JP2</h2>
<p>The following Table (taken from Table I.2 in ISO/IEC 15444-1, with minor modifications) lists all boxes that are defined in the standard. Addition signs in the ‘box name’ column indicate boxes that are children of a ‘superbox’.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Box name</th>
<th style="text-align: left;">Superbox</th>
<th style="text-align: left;">Required?</th>
<th style="text-align: left;">Purpose</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">JPEG 2000 Signature box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Required</td>
<td style="text-align: left;">Identifies the file as being part of the JPEG 2000 family of files.</td>
</tr>
<tr class="even">
<td style="text-align: left;">File Type box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Required</td>
<td style="text-align: left;">Specifies file type, version and compatibility information, including specifying if this file is a conforming JP2 file or if it can be read by a conforming JP2 reader.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">JP2 Header box</td>
<td style="text-align: left;">Yes</td>
<td style="text-align: left;">Required</td>
<td style="text-align: left;">Contains a series of boxes that contain header-type information about the file.</td>
</tr>
<tr class="even">
<td style="text-align: left;">+ Image Header box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Required</td>
<td style="text-align: left;">Specifies the size of the image and other related fields.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">+ Bits Per Component box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies the bit depth of the components in the file in cases where the bit depth is not constant across all components.</td>
</tr>
<tr class="even">
<td style="text-align: left;">+ Colour Specification box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Required</td>
<td style="text-align: left;">Specifies the colourspace of the image.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">+ Palette box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies the palette which maps a single component in index space to a multiple-component image.</td>
</tr>
<tr class="even">
<td style="text-align: left;">+ Component Mapping box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies the mapping between a palette and codestream components.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">+ Channel Definition box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies the type and ordering of the components within the codestream, as well as those created by the application of a palette.</td>
</tr>
<tr class="even">
<td style="text-align: left;">+ Resolution box</td>
<td style="text-align: left;">Yes</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Contains the grid resolution.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">++ Capture Resolution box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies the grid resolution at which the image was captured.</td>
</tr>
<tr class="even">
<td style="text-align: left;">++ Default Display Resolution box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies the default grid resolution at which the image should be displayed.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Contiguous Codestream box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Required</td>
<td style="text-align: left;">Contains the codestream.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Intellectual Property box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Contains intellectual property information about the image.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">XML box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Provides a tool by which vendors can add XML formatted information to a JP2 file.</td>
</tr>
<tr class="even">
<td style="text-align: left;">UUID box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Provides a tool by which vendors can add additional information to a file without risking conflict with other vendors.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">UUID Info box</td>
<td style="text-align: left;">Yes</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Provides a tool by which a vendor may provide access to additional information associated with a UUID.</td>
</tr>
<tr class="even">
<td style="text-align: left;">+ UUID List box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies a list of UUIDs.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">+ URL box</td>
<td style="text-align: left;">No</td>
<td style="text-align: left;">Optional</td>
<td style="text-align: left;">Specifies a URL.</td>
</tr>
</tbody>
</table>
<p>A JP2 file may contain boxes that are not defined by the standard. Such boxes are simply skipped and ignored by conforming reader applications.</p>
<h1 id="output-format"><span class="header-section-number">5</span> Output format</h1>
<p>This chapter explains <em>jpylyzer</em>’s output format.</p>
<h2 id="output-format-overview"><span class="header-section-number">5.1</span> Overview</h2>
<p><em>Jpylyzer</em> generates its output in XML format, which is defined by <a href="http://jpylyzer.openpreservation.org/jpylyzer-v-2-0.xsd">the schema that can be found here</a>. The following Figure shows the output structure:</p>
<figure>
<img src="images/outputStructure.png" alt="Jpylyzer’s XML output structure. ‘box’ elements under ‘tests’ and ‘properties’ contain further sub-elements."><figcaption>Jpylyzer’s XML output structure. ‘box’ elements under ‘tests’ and ‘properties’ contain further sub-elements.</figcaption>
</figure>
<p>The root element (<em>jpylyzer</em>) contains the following child elements:</p>
<ol type="1">
<li><p>one <em>toolInfo</em> element, which contains information about <em>jpylyzer</em></p></li>
<li><p>one or more <em>file</em> elements, each of which contain information about about the analysed files</p></li>
</ol>
<p>The XML output is pretty-printed. You can use the <code>--nopretty</code> switch to disable pretty-printing (this produces smaller files and may give a slightly better performance).</p>
<h2 id="toolinfo-element"><span class="header-section-number">5.2</span> toolInfo element</h2>
<p>This element holds information about <em>jpylyzer</em>. Currently it contains the following sub-elements:</p>
<ul>
<li><p><em>toolName</em>: name of the analysis tool (i.e. <em>jpylyzer</em> or <em>jpylyzer.exe</em>, depending on the platform used)</p></li>
<li><p><em>toolVersion</em>: version of <em>jpylyzer</em> (<em>jpylyzer</em> uses a date versioning scheme)</p></li>
</ul>
<h2 id="file-element"><span class="header-section-number">5.3</span> file element</h2>
<p>The <em>file</em> element contains the following sub-elements:</p>
<ol type="1">
<li><p><em>fileInfo</em>: general information about the analysed file</p></li>
<li><p><em>statusInfo</em>: information about the status of <em>jpylyzer</em>’s validation attempt</p></li>
<li><p><em>isValid</em>: outcome of the validation</p></li>
<li><p><em>tests</em>: outcome of the individual tests that are part of the validation process (organised by box)</p></li>
<li><p><em>properties</em>: image properties (organised by box)</p></li>
<li><p><em>propertiesExtension</em>: wrapper element for NISO <em>MIX</em> output (only if the <code>--mix</code> option is used)</p></li>
</ol>
<h2 id="fileinfo-element"><span class="header-section-number">5.4</span> fileInfo element</h2>
<p>This element holds general information about the analysed file. Currently it contains the following sub-elements:</p>
<ul>
<li><p><em>filename</em>: name of the analysed file without its path (e.g. “rubbish.jp2”)</p></li>
<li><p><em>filePath</em>: name of the analysed file, including its full absolute path (e.g. “d:\data\images\rubbish.jp2”)</p></li>
<li><p><em>fileSizeInBytes</em>: file size in bytes</p></li>
<li><p><em>fileLastModified</em>: last modified date and time</p></li>
</ul>
<h2 id="statusinfo-element"><span class="header-section-number">5.5</span> statusInfo element</h2>
<p>This element holds general information about about the status of <em>jpylyzer</em>’s attempt at validating a file. It tells you whether the validation process could be completed without any internal <em>jpylyzer</em> errors. It contains the following sub-elements:</p>
<ul>
<li><p><em>success</em>: a Boolean flag that indicates whether the validation attempt completed normally (“True”) or not (“False”). A value of “False” indicates an internal error that prevented <em>jpylyzer</em> from validating the file.</p></li>
<li><p><em>failureMessage</em>: if the validation attempt failed (value of <em>success</em> equals “False”), this field gives further details about the reason of the failure. Examples are:</p>
<ul>
<li><code>memory error (file size too large)</code></li>
<li><code>runtime error (please report to developers)</code></li>
<li><code>unknown error (please report to developers)</code></li>
</ul></li>
</ul>
<h2 id="isvalid-element"><span class="header-section-number">5.6</span> isValid element</h2>
<p>This element contains the results of the validation. If a file passed all the tests (i.e. all tests returned “True”, see <a href="#tests-element">section 5.7</a>) it is most likely valid, and the value of <em>isValid</em> will be “True”. Its value is “False” otherwise. The element has a <em>format</em> attribute, which defines the validation format (set by the <code>--format</code> command-line option). The <em>format</em> attribute can have the following values:</p>
<ul>
<li>“jp2” (JP2 validation)</li>
<li>“j2c” (raw codestream validation)</li>
</ul>
<h2 id="tests-element"><span class="header-section-number">5.7</span> tests element</h2>
<p>This element is reserved to hold the outcomes of all the individual tests that <em>jpylyzer</em> performs to assess whether a file is valid JP2. The results are organised in a hierarchical tree that corresponds to JP2’s box structure. Each individual test can have two values:</p>
<ul>
<li><p>“True” if a file passed the test.</p></li>
<li><p>“False” if a file failed the test.</p></li>
</ul>
<p>If a file passed <em>all</em> tests, this is an indication that it is most likely valid JP2. In that case, the <em>isValid</em> element (<a href="#isvalid-element">section 5.6</a>) has a value of “True” (and “False” in all other cases). These tests are all explained in chapters <a href="#jp2-box-by-box">6</a> and <a href="#contiguous-codestream-box-chapter">7</a>.</p>
<h3 id="default-and-verbose-reporting-of-test-results"><span class="header-section-number">5.7.1</span> Default and verbose reporting of test results</h3>
<p>By default, <em>jpylyzer</em> only reports any tests that failed (i.e. returned “False”), including the corresponding part of the box structure. For a valid JP2 the tests element will be empty. If the –verbose flag is used, the results of <em>all</em> tests are included (including those that returned “True”)<a href="#fn3" class="footnote-ref" id="fnref3"><sup>3</sup></a>.</p>
<h2 id="properties-element"><span class="header-section-number">5.8</span> properties element</h2>
<p>This element contains the extracted image properties, which are organised in a hierarchical tree that corresponds to JP2’s box structure. See chapters <a href="#jp2-box-by-box">6</a> and <a href="#contiguous-codestream-box-chapter">7</a> for a description of the reported properties.</p>
<h2 id="propertiesExtension-element"><span class="header-section-number">5.9</span> propertiesExtension element</h2>
<p>This optional element is reserved for output in alternative formats. Currently it is used to wrap output in NISO <em>MIX</em> format if the <code>--mix</code> option is used. See the <a href="http://www.loc.gov/standards/mix/"><em>MIX</em> documentation</a> for a description of the reported elements.</p>
<h1 id="jp2-box-by-box"><span class="header-section-number">6</span> JP2: box by box</h1>
<p>The following two chapters provide a detailed explanation of <em>jpylyzer</em>’s functionality and its output. In particular, the following two aspects are addressed:</p>
<ol type="1">
<li><p>The reported properties</p></li>
<li><p>The tests that <em>jpylyzer</em> performs to establish the validity of a file.</p></li>
</ol>
<h2 id="about-properties-tests-trees"><span class="header-section-number">6.1</span> About the properties and tests trees</h2>
<p>The ‘properties’ element in <em>jpylyzer</em>’s output holds a hierarchical tree structure that contains all extracted properties. The ‘tests’ tree follows the same structure. The hierarchy reflects JP2’s box structure (explained in <a href="#structure-jp2">Chapter 4</a>): each box is represented by a corresponding output element that contains the corresponding property entries. If a box is a superbox, the output element will contain child elements for each child box. For some boxes, the output contains further sub-elements. This applies in particular to the Contiguous Codestream box, since its contents are more complex than any of the other boxes. Also, if a Colour Specification box contains an embedded ICC profile, the properties of the ICC profile are stored in a separate sub-element. In addition to this, one ‘property’ that is reported by <em>jpylyzer</em> (the compression ratio) is not actually extracted from any particular box. Instead, it is calculated from the file size and some properties from the Header boxes. As a result, it is reported separately in the root of the properties tree.</p>
<h3 id="naming-of-properties"><span class="header-section-number">6.1.1</span> Naming of properties</h3>
<p>The naming of the reported properties largely follows the standard (ISO/IEC 15444-1). Some minor differences follow from the fact that the standard does have any consistent use of text case, whereas <em>jpylyzer</em> uses lower camel case. In addition, some parameters in the standard are compound units that aggregate a number of Boolean ‘switches’, where no names are provided for each individual switch. An example of this is the <em>Scod</em> (coding style) parameter in the codestream header, which contains three switches that define the use of precincts, start-of-packet markers and end-of-packet markers. For cases like these <em>jpylyzer</em> uses its own (largely self-descriptive) names (which are all documented in these chapters).</p>
<h2 id="jpeg2000-signature-box"><span class="header-section-number">6.2</span> JPEG 2000 Signature box</h2>
<p>This box contains information that allows identification of the file as being part of the JPEG 2000 family of file formats.</p>
<h3 id="element-name"><span class="header-section-number">6.2.1</span> Element name</h3>
<p>signatureBox</p>
<h3 id="reported-properties"><span class="header-section-number">6.2.2</span> Reported properties</h3>
<p>None (box only holds JPEG 2000 signature, which includes non-printable characters)</p>
<h3 id="tests"><span class="header-section-number">6.2.3</span> Tests</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Test name</th>
<th style="text-align: left;">True if</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">boxLengthIsValid</td>
<td style="text-align: left;">Size of box contents equals 4 bytes</td>
</tr>
<tr class="even">
<td style="text-align: left;">signatureIsValid</td>
<td style="text-align: left;">Signature equals 0x0d0a870a</td>
</tr>
</tbody>
</table>
<h2 id="file-type-box"><span class="header-section-number">6.3</span> File Type box</h2>
<p>This box specifies file type, version and compatibility information, including specifying if this file is a conforming JP2 file or if it can be read by a conforming JP2 reader.</p>
<h3 id="element-name-1"><span class="header-section-number">6.3.1</span> Element name</h3>
<p>fileTypeBox</p>
<h3 id="reported-properties-1"><span class="header-section-number">6.3.2</span> Reported properties</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Property</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">br</td>
<td style="text-align: left;">Brand</td>
</tr>
<tr class="even">
<td style="text-align: left;">minV</td>
<td style="text-align: left;">Minor version</td>
</tr>
<tr class="odd">
<td style="text-align: left;">cL<sup>*</sup></td>
<td style="text-align: left;">Compatibility field (repeatable)</td>
</tr>
</tbody>
</table>
<h3 id="tests-1"><span class="header-section-number">6.3.3</span> Tests</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Test name</th>
<th style="text-align: left;">True if</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">boxLengthIsValid</td>
<td style="text-align: left;">(Size of box – 8) /4 is a whole number (integer)</td>
</tr>
<tr class="even">
<td style="text-align: left;">brandIsValid</td>
<td style="text-align: left;"><em>br</em> equals 0x6a703220 (“jp2”)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">minorVersionIsValid</td>
<td style="text-align: left;"><em>minV</em> equals 0</td>
</tr>
<tr class="even">
<td style="text-align: left;">compatibilityListIsValid</td>
<td style="text-align: left;">Sequence of compatibility (<em>cL</em>) fields includes one entry that equals 0x6a703220 (“jp2”)</td>
</tr>
</tbody>
</table>
<h2 id="jp2-header-box"><span class="header-section-number">6.4</span> JP2 Header box (superbox)</h2>
<p>This box is a superbox that holds a series of boxes that contain header-type information about the file.</p>
<h3 id="element-name-2"><span class="header-section-number">6.4.1</span> Element name</h3>
<p>jp2HeaderBox</p>
<h3 id="reported-properties-2"><span class="header-section-number">6.4.2</span> Reported properties</h3>
<p>Since this is a superbox, it contains a number of child boxes. These are represented as child elements in the properties tree:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Child element</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">imageHeaderBox (<a href="#image-header-box">section 6.5</a>)</td>
<td style="text-align: left;">Properties from Image Header box (required)</td>
</tr>
<tr class="even">
<td style="text-align: left;">bitsPerComponentBox (<a href="#bits-per-component-box">section 6.6</a>)</td>
<td style="text-align: left;">Properties from Bits Per Component box (optional)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">ColourSpecificationBox (<a href="#colour-specification-box">section 6.7</a>)</td>
<td style="text-align: left;">Properties from Colour Specification box (required)</td>
</tr>
<tr class="even">
<td style="text-align: left;">paletteBox (<a href="#palette-box">section 6.8</a>)</td>
<td style="text-align: left;">Properties from Palette box (optional)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">componentMappingBox (<a href="#component-mapping-box">section 6.9</a>)</td>
<td style="text-align: left;">Properties from Component Mapping box (optional)</td>
</tr>
<tr class="even">
<td style="text-align: left;">channelDefinitionBox (<a href="#channel-definition-box">section 6.10</a>)</td>
<td style="text-align: left;">Properties from Channel Definition box (optional)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">resolutionBox (<a href="#resolution-box">section 6.11</a>)</td>
<td style="text-align: left;">Properties from Resolution box (optional)</td>
</tr>
</tbody>
</table>
<h3 id="tests-2"><span class="header-section-number">6.4.3</span> Tests</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Test name</th>
<th style="text-align: left;">True if</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">containsImageHeaderBox</td>
<td style="text-align: left;">Box contains required Image Header box</td>
</tr>
<tr class="even">
<td style="text-align: left;">containsColourSpecificationBox</td>
<td style="text-align: left;">Box contains required Colour Specification box</td>
</tr>
<tr class="odd">
<td style="text-align: left;">containsBitsPerComponentBox</td>
<td style="text-align: left;">Box contains Bits Per Component Box, which is required if <em>bPCSign</em> and <em>bPCDepth</em> in Image Header Box equal 1 and 128, respectively (test is skipped otherwise)</td>
</tr>
<tr class="even">
<td style="text-align: left;">firstJP2HeaderBoxIsImageHeaderBox</td>
<td style="text-align: left;">First child box is Image Header Box</td>
</tr>
<tr class="odd">
<td style="text-align: left;">noMoreThanOneImageHeaderBox</td>
<td style="text-align: left;">Box contains no more than one Image Header box</td>
</tr>
<tr class="even">
<td style="text-align: left;">noMoreThanOneBitsPerComponentBox</td>
<td style="text-align: left;">Box contains no more than one Bits Per Component box</td>
</tr>
<tr class="odd">
<td style="text-align: left;">noMoreThanOnePaletteBox</td>
<td style="text-align: left;">Box contains no more than one Palette box</td>
</tr>
<tr class="even">
<td style="text-align: left;">noMoreThanOneComponentMappingBox</td>
<td style="text-align: left;">Box contains no more than one Component Mapping box</td>
</tr>
<tr class="odd">
<td style="text-align: left;">noMoreThanOneChannelDefinitionBox</td>
<td style="text-align: left;">Box contains no more than one Channel Definition box</td>
</tr>
<tr class="even">
<td style="text-align: left;">noMoreThanOneResolutionBox</td>
<td style="text-align: left;">Box contains no more than one Resolution box</td>
</tr>
<tr class="odd">
<td style="text-align: left;">colourSpecificationBoxesAreContiguous</td>
<td style="text-align: left;">In case of multiple Colour Specification boxes, they appear contiguously in the JP2 Header box</td>
</tr>
<tr class="even">
<td style="text-align: left;">paletteAndComponentMappingBoxesOnlyTogether</td>
<td style="text-align: left;">Box contains a Palette box (only if Component Mapping box is present); box contains a Component Mapping box (only if Palette box is present)</td>
</tr>
</tbody>
</table>
<h2 id="image-header-box"><span class="header-section-number">6.5</span> Image Header box (child of JP2 Header box)</h2>
<p>This box specifies the size of the image and other related fields.</p>
<h3 id="element-name-3"><span class="header-section-number">6.5.1</span> Element name</h3>
<p>imageHeaderBox</p>
<h3 id="reported-properties-3"><span class="header-section-number">6.5.2</span> Reported properties</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Property</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">height</td>
<td style="text-align: left;">Image height in pixels</td>
</tr>
<tr class="even">
<td style="text-align: left;">width</td>
<td style="text-align: left;">Image width in pixels</td>
</tr>
<tr class="odd">
<td style="text-align: left;">nC</td>
<td style="text-align: left;">Number of image components</td>
</tr>
<tr class="even">
<td style="text-align: left;">bPCSign</td>
<td style="text-align: left;">Indicates whether image components are signed or unsigned</td>
</tr>
<tr class="odd">
<td style="text-align: left;">bPCDepth</td>
<td style="text-align: left;">Number of bits per component</td>
</tr>
<tr class="even">
<td style="text-align: left;">c</td>
<td style="text-align: left;">Compression type</td>
</tr>
<tr class="odd">
<td style="text-align: left;">unkC</td>
<td style="text-align: left;">Colourspace Unknown field (“yes” if colourspace of image data is unknown; “no” otherwise)</td>
</tr>
<tr class="even">
<td style="text-align: left;">iPR</td>
<td style="text-align: left;">Intellectual Property field (“yes” if image contains intellectual property rights information; “no” otherwise)</td>
</tr>
</tbody>
</table>
<h3 id="tests-3"><span class="header-section-number">6.5.3</span> Tests</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Test name</th>
<th style="text-align: left;">True if</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">boxLengthIsValid</td>
<td style="text-align: left;">Size of box contents equals 14 bytes</td>
</tr>
<tr class="even">
<td style="text-align: left;">heightIsValid</td>
<td style="text-align: left;"><em>height</em> is within range [1, 2<sup>32</sup> - 1]</td>
</tr>
<tr class="odd">
<td style="text-align: left;">widthIsValid</td>
<td style="text-align: left;"><em>width</em> is within range [1, 2<sup>32</sup> - 1]</td>
</tr>
<tr class="even">
<td style="text-align: left;">nCIsValid</td>
<td style="text-align: left;"><em>nC</em> is within range [1, 16384]</td>
</tr>
<tr class="odd">
<td style="text-align: left;">bPCIsValid</td>
<td style="text-align: left;"><em>bPCDepth</em> is within range [1,38] OR <em>bPCSign</em> equals 255 (in the latter case the bit depth is variable)</td>
</tr>
<tr class="even">
<td style="text-align: left;">cIsValid</td>
<td style="text-align: left;"><em>c</em> equals 7 (“jpeg2000”)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">unkCIsValid</td>
<td style="text-align: left;"><em>unkC</em> equals 0 (“no”) or 1 (“yes”)</td>
</tr>
<tr class="even">
<td style="text-align: left;">iPRIsValid</td>
<td style="text-align: left;"><em>iPR</em> equals 0 (“no”) or 1 (“yes”)</td>
</tr>
</tbody>
</table>
<h2 id="bits-per-component-box"><span class="header-section-number">6.6</span> Bits Per Component box (child of JP2 Header box)</h2>
<p>This (optional) box specifies the bit depth of the components in the file in cases where the bit depth is not constant across all components.</p>
<h3 id="element-name-4"><span class="header-section-number">6.6.1</span> Element name</h3>
<p>bitsPerComponentBox</p>
<h3 id="reported-properties-4"><span class="header-section-number">6.6.2</span> Reported properties</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Property</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">bPCSign<sup>*</sup></td>
<td style="text-align: left;">Indicates whether image component is signed or unsigned (repeated for all components)</td>
</tr>
<tr class="even">
<td style="text-align: left;">bPCDepth<sup>*</sup></td>
<td style="text-align: left;">Number of bits for this component (repeated for all components)</td>
</tr>
</tbody>
</table>
<h3 id="tests-4"><span class="header-section-number">6.6.3</span> Tests</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Test name</th>
<th style="text-align: left;">True if</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">bPCIsValid<sup>*</sup></td>
<td style="text-align: left;"><em>bPCDepth</em> is within range [1,38] (repeated for all components)</td>
</tr>
</tbody>
</table>
<h2 id="colour-specification-box"><span class="header-section-number">6.7</span> Colour Specification box (child of JP2 Header box)</h2>
<p>This box specifies the colourspace of the image.</p>
<h3 id="element-name-5"><span class="header-section-number">6.7.1</span> Element name</h3>
<p>colourSpecificationBox</p>
<h3 id="reported-properties-5"><span class="header-section-number">6.7.2</span> Reported properties</h3>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Property</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">meth</td>
<td style="text-align: left;">Specification method. Indicates whether colourspace of this image is defined as an enumerated colourspace or using a (restricted) ICC profile.</td>
</tr>
<tr class="even">
<td style="text-align: left;">prec</td>
<td style="text-align: left;">Precedence</td>
</tr>
<tr class="odd">
<td style="text-align: left;">approx</td>
<td style="text-align: left;">Colourspace approximation</td>
</tr>
<tr class="even">
<td style="text-align: left;">enumCS (if meth equals “Enumerated”)</td>
<td style="text-align: left;">Enumerated colourspace (as descriptive text string)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">icc (if meth equals “Restricted ICC” or “Any ICC”<a href="#fn4" class="footnote-ref" id="fnref4"><sup>4</sup></a>)</td>
<td style="text-align: left;">Properties of ICC profile as child element (see below)</td>
</tr>
</tbody>
</table>
<h3 id="reported-properties-of-icc-profiles"><span class="header-section-number">6.7.3</span> Reported properties of ICC profiles</h3>
<p>If the colour specification box contains an embedded ICC profile, <em>jpylyzer</em> will also report the following properties (which are all grouped in an “icc” sub-element in the properties tree). An exhaustive explanation of these properties is given in the ICC specification (ISO 15076-1 / ICC.1:2004-10). Note that <em>jpylyzer</em> does <em>not</em> validate embedded ICC profiles (even though it does check if a specific ICC profile is allowed in JP2)!</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Property</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">profileSize</td>
<td style="text-align: left;">Size of ICC profile in bytes</td>
</tr>
<tr class="even">
<td style="text-align: left;">preferredCMMType</td>
<td style="text-align: left;">Preferred CMM type</td>
</tr>
<tr class="odd">
<td style="text-align: left;">profileVersion</td>
<td style="text-align: left;">Profile version. Format: “majorRevision.minorRevision.bugFixRevision”</td>
</tr>
<tr class="even">
<td style="text-align: left;">profileClass</td>
<td style="text-align: left;">Profile/device class</td>
</tr>
<tr class="odd">
<td style="text-align: left;">colourSpace</td>
<td style="text-align: left;">Colourspace</td>
</tr>
<tr class="even">
<td style="text-align: left;">profileConnectionSpace</td>
<td style="text-align: left;">Profile connection space</td>
</tr>
<tr class="odd">
<td style="text-align: left;">dateTimeString</td>
<td style="text-align: left;">Date / time string. Format: “YYYY/MM/DD, h:m:s”</td>
</tr>
<tr class="even">
<td style="text-align: left;">profileSignature</td>
<td style="text-align: left;">Profile signature</td>
</tr>
<tr class="odd">
<td style="text-align: left;">primaryPlatform</td>
<td style="text-align: left;">Primary platform</td>
</tr>
<tr class="even">
<td style="text-align: left;">embeddedProfile</td>
<td style="text-align: left;">Flag that indicates whether profile is embedded in file (“yes”/”no”)</td>
</tr>