applications/jpip/README

   1 ========================================================================
   2                     OpenJPIP software 1.0 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 First Version 1.0 covers:
  30  - JPT-stream (Tile based) media types
  31  - Session, channels, cache model managements
  32  - JPIP over HTTP
  33  - Indexing JPEG 2000 files
  34  - Embedding XML formatted metadata
  35  - Region Of Interest (ROI) requests
  36
  37 ----------
  38 2. License
  39 ----------
  40
  41 This software is released under the BSD license, anybody can use or modify the library, even for commercial applications.
  42 The only restriction is to retain the copyright in the sources or the binaries documentation.
  43 Neither the author, nor the university accept any responsibility for any kind of error or data loss which may occur during usage.
  44
  45 ----------
  46 3. System requirements
  47 ----------
  48
  49  - OpenJPEG library (currently assumes it is installed on the system => will not use the one built higher in the directory structure)
  50  - FastCGI development kit (C libraries) at server (http://www.fastcgi.com)
  51  - Java application launcher at client
  52  - Kakadu software ( http://www.kakadusoftware.com). Currently required to encode jpeg 2000 images with tile-parts. This will be implemented soon in openjpeg, making this requirement obsolete.
  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 CMake files ar planned to be included ASAP.
  66
  67 The documentation can be build this way (requires doxygen utility):
  68   cd doc
  69   doxygen Doxyfile
  70
  71 ----------
  72 5. Usage
  73 ----------
  74
  75 Preliminary notes :
  76   * HTML documentation is available at http://www.openjpeg.org/jpip/doc/html
  77   * Example image is available at http://www.openjpeg.org/jpip/data/copenhague1.zip (20 Mb !)
  78
  79 Webserver:
  80   You need a webserver running with the fastcgi module enabled and correctly configured.
  81   For Apache, add the following line to your /etc/apache2/mods-available/fastcgi.conf configuration file:
  82
  83       FastCGIExternalServer /var/www/myFCGI -host localhost:3000
  84
  85   where /var/www is your DocumentRoot.
  86   Please refer to 'http://www.openjpeg.org/jpip/doc/ApacheFastCGITutorial.pdf' for more details.
  87
  88 Server:
  89  1. Store JP2 files in the same directory as opj_server
  90
  91  2. Launch opj_server from the server terminal:
  92     % spawn-fcgi -f ./opj_server -p 3000 -n
  93
  94  For shutting down JPIP server:
  95      %GET http://hostname/myFCGI?quitJPIP
  96      Notice, http://hostname/myFCGI is the HTTP server URI (myFCGI refers to opj_server by the server setting)
  97      Requst message "quitJPIP" can be changed in Makfile, modify -DQUIT_SIGNAL=\"quitJPIP\"
  98
  99 Client:
 100  1. Launch image decoding server, and keep it alive as long as image viewers are open
 101     % ./opj_dec_server
 102
 103     You might prefer to implement this program from another directory since cache files are saved in the working directory.
 104     % mkdir cache
 105     % cd cache
 106     % ../opj_dec_server
 107
 108  2. Open image viewers (as many as needed)
 109     % java -jar opj_viewer.jar http://hostname/myFCGI JP2_filename.jp2 [stateless]
 110     ( The arguments
 111       - http://hostname/myFCGI is the HTTP server URI (myFCGI refers to opj_server by the server setting)
 112       - JP2_filename.jp2 is the name of a JP2 file available on the server.
 113       - stateless if stateless request is desired, otherwise session request is implemented
 114     Image viewer GUI instructions:
 115       Scale up request: Enlarge the window
 116       ROI request:      Select a region by mouse click and drag, then click inside the red frame of the selected region
 117     <If Xerces2 is installed>
 118     % java -jar opj_viewer_xerces.jar http://hostname/myFCGI JP2_filename.jp2
 119       Annotate image with ROI information in XML metadata: Click button "Region Of Interest"
 120       Open a new window presenting an aligned image with a locally stored image: Click button "Image Registration" (Under Construction)
 121
 122  3. Quit the image decoding server through the telnet, be sure all image viewers are closed
 123     % telnet localhost 5000
 124       quit
 125
 126 ----------
 127 5. JP2 encoding instructions
 128 ----------
 129
 130 An example to encode a TIF image "copenhague1.tif" at resolution 4780x4050, 8bit/pixel, grayscale.
 131
 132  1. J2K encoding using Kakadu with an option which introduces the tile-part flag at each resolution level
 133     % ./kdu_compress -i copenhague1.tif -o copenhague1.j2k Corder=RPCL  ORGtparts=R Stiles={256,256}
 134
 135  2. JP2 encoding with embedding indexing data
 136     % ./j2k_to_idxjp2 copenhague1.j2k copenhague1.jp2
 137
 138 <Option>
 139  3. Embed metadata into JP2 file
 140     % ./addXMLinJP2 copenhague1.jp2 copenhague1.xml
 141     Input metadata file "copenhague1.xml" looks like:
 142     <xmlbox>
 143       <roi name="island" x="1890" y="1950" w="770" h="310"/>
 144       <roi name="ship" x="750" y="330" w="100" h="60"/>
 145       <roi name="airport" x="650" y="1800" w="650" h="800"/>
 146       <roi name="harbor" x="4200" y="1650" w="130" h="130"/>
 147       <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"/>
 148     </xmlbox>