src/bin/jpip/README

   1 ========================================================================
   2                     OpenJPIP software 2.1 ReadMe
   3
   4 OpenJPEG:
   5 http://www.openjpeg.org
   6
   7 Written by:
   8 Kaori Hagihara
   9 UCL/SST/ICTM/ELEN
  10 February 18 2011
  11 ========================================================================
  12
  13 Contents:
  14 1. Introduction
  15 2. License
  16 3. System requirements
  17 4. Implementing instructions
  18 5. JP2 encoding instructions
  19
  20
  21 ----------
  22 1. Introduction
  23 ----------
  24
  25 OpenJPIP 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)
  27 The current implementation uses some results from the 2KAN project (http://www.2kan.org).
  28
  29 Version 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 ----------
  39 2. License
  40 ----------
  41
  42 This software is released under the BSD license, anybody can use or modify the library, even for commercial applications.
  43 The only restriction is to retain the copyright in the sources or the binaries documentation.
  44 Neither the author, nor the university accept any responsibility for any kind of error or data loss which may occur during usage.
  45
  46 ----------
  47 3. 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
  56 We tested this software with a virtual server running on the same Linux machine as the clients.
  57
  58 ----------
  59 4. Building instructions
  60 ----------
  61
  62 A Makefile is available in the same directory as this README file. Simply type 'make' and it will build all the required C-executables.
  63 Concerning the java-based opj_viewer, simply type 'ant' in the corresponding directory (requires 'ant' utility of course)
  64
  65 The documentation can be build this way (requires doxygen utility):
  66   cd doc
  67   doxygen Doxyfile
  68
  69 ----------
  70 5. Usage
  71 ----------
  72
  73 Preliminary 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
  77 Webserver:
  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
  86 Server:
  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      Request message "quitJPIP" can be changed in Makefile, modify -DQUIT_SIGNAL=\"quitJPIP\"
  96
  97 Client:
  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 ----------
 129 5. JP2 encoding instructions
 130 ----------
 131
 132 An 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>