README
1========================================================================
2 OpenJPIP software 2.1 ReadMe
3
4OpenJPEG:
5http://www.openjpeg.org
6
7Written by:
8Kaori Hagihara
9UCL/SST/ICTM/ELEN
10February 18 2011
11========================================================================
12
13Contents:
141. Introduction
152. License
163. System requirements
174. Implementing instructions
185. JP2 encoding instructions
19
20
21----------
221. Introduction
23----------
24
25OpenJPIP software is an implementation of JPEG 2000 Part9: Interactivity tools, APIs and protocols (JPIP).
26( For more info about JPIP, check the website: http://www.jpeg.org/jpeg2000/j2kpart9.html)
27The current implementation uses some results from the 2KAN project (http://www.2kan.org).
28
29Version 2.1 covers:
30 - JPT-stream (Tile) and JPP-stream (Precinct) media types
31 - Session, channels, cache model managements
32 - JPIP over HTTP, HTTP requests and TCP return
33 - Indexing JPEG 2000 files
34 - Embedding XML formatted metadata
35 - Region Of Interest (ROI) requests
36 - Access to JP2 files with their URL
37
38----------
392. License
40----------
41
42This software is released under the BSD license, anybody can use or modify the library, even for commercial applications.
43The only restriction is to retain the copyright in the sources or the binaries documentation.
44Neither the author, nor the university accept any responsibility for any kind of error or data loss which may occur during usage.
45
46----------
473. System requirements
48----------
49
50 - FastCGI development kit (C libraries) at server (http://www.fastcgi.com)
51 - libcURL library
52 - Java application launcher at client
53<Optional>
54 - Xerces2 java XML parser on the client for accessing embedded image metadata (http://xerces.apache.org/xerces2-j)
55
56We tested this software with a virtual server running on the same Linux machine as the clients.
57
58----------
594. Building instructions
60----------
61
62A Makefile is available in the same directory as this README file. Simply type 'make' and it will build all the required C-executables.
63Concerning the java-based opj_viewer, simply type 'ant' in the corresponding directory (requires 'ant' utility of course)
64
65The documentation can be build this way (requires doxygen utility):
66 cd doc
67 doxygen Doxyfile
68
69----------
705. Usage
71----------
72
73Preliminary notes :
74 * HTML documentation is available at http://www.openjpeg.org/jpip/doc/html
75 * Example image is available at http://www.openjpeg.org/jpip/data/copenhague1.zip (20 Mb !)
76
77Webserver:
78 You need a webserver running with the fastcgi module enabled and correctly configured.
79 For Apache, add the following line to your /etc/apache2/mods-available/fastcgi.conf configuration file:
80
81 FastCGIExternalServer /var/www/myFCGI -host localhost:3000
82
83 where /var/www is your DocumentRoot.
84 Please refer to 'http://www.openjpeg.org/jpip/doc/ApacheFastCGITutorial.pdf' for more details.
85
86Server:
87 1. Store JP2 files in the same directory as opj_server
88
89 2. Launch opj_server from the server terminal:
90 % spawn-fcgi -f ./opj_server -p 3000 -n
91
92 For shutting down JPIP server:
93 %GET http://hostname/myFCGI?quitJPIP
94 Notice, http://hostname/myFCGI is the HTTP server URI (myFCGI refers to opj_server by the server setting)
95 Requst message "quitJPIP" can be changed in Makfile, modify -DQUIT_SIGNAL=\"quitJPIP\"
96
97Client:
98 1. Launch image decoding server, and keep it alive as long as image viewers are open
99 % ./opj_dec_server [portnumber (50000 by default)]
100
101 You might prefer to implement this program from another directory since cache files are saved in the working directory.
102 % mkdir cache
103 % cd cache
104 % ../opj_dec_server
105
106 2. Open image viewers (as many as needed)
107 % java -jar opj_viewer.jar http://hostname/myFCGI path/filename.jp2 [hostname] [portnumber] [stateless/session] [jptstream/jppstream] [tcp/udp]
108 ( The arguments
109 - http://hostname/myFCGI is the HTTP server URI (myFCGI refers to opj_server by the server setting)
110 - path/filename.jp2 is the server local path or URL of a JP2 file
111 - host name of opj_dec_server, localhost by default
112 - portnumber of opj_dec_server, 50000 by default
113 - request type stateless for no caching, session (default) for caching
114 - return media type, JPT-stream tile based stream, or JPP-stream (default) precinct based stream
115 - auxiliary return protocol, tcp or udp (udp is not implemented yet), if not given, return data is filled in http chunk
116 Image viewer GUI instructions:
117 Scale up request: Enlarge the window
118 ROI request: Select a region by mouse click and drag, then click inside the red frame of the selected region
119 <If Xerces2 is installed>
120 % java -jar opj_viewer_xerces.jar http://hostname/myFCGI JP2_filename.jp2
121 Annotate image with ROI information in XML metadata: Click button "Region Of Interest"
122 Open a new window presenting an aligned image with a locally stored image: Click button "Image Registration" (Under Construction)
123
124 3. Quit the image decoding server through the telnet, be sure all image viewers are closed
125 % telnet localhost 50000
126 quit
127
128----------
1295. JP2 encoding instructions
130----------
131
132An example to encode a TIF image "copenhague1.tif" at resolution 4780x4050, 8bit/pixel, grayscale.
133 % ./image_to_j2k -i copenhague1.tif -o copenhague1.jp2 -p RPCL -c [64,64] -t 640,480 -jpip -TP R
134
135 options
136 -jpip : embed index table 'cidx' box into the output JP2 file (obligation for JPIP)
137 -TP R : partition a tile into tile parts of different resolution levels (obligation for JPT-stream)
138
139<Option>
140 3. Embed metadata into JP2 file
141 % ./addXMLinJP2 copenhague1.jp2 copenhague1.xml
142 Input metadata file "copenhague1.xml" looks like:
143 <xmlbox>
144 <roi name="island" x="1890" y="1950" w="770" h="310"/>
145 <roi name="ship" x="750" y="330" w="100" h="60"/>
146 <roi name="airport" x="650" y="1800" w="650" h="800"/>
147 <roi name="harbor" x="4200" y="1650" w="130" h="130"/>
148 <irt refimg="name1.jp2" m1="0.50" m2="-0.50" m3="0" m4="0.80" m5="-0.80" m6="0" m7="500" m8="1000" m9="0"/>
149 </xmlbox>
150
){kind=link}