======================================================================== * README.md ======================================================================== # OPENJPEG Library and Applications ## What is OpenJPEG ? OpenJPEG is an open-source JPEG 2000 codec written in C language. It has been developed in order to promote the use of [JPEG 2000](http://www.jpeg.org/jpeg2000), a still-image compression standard from the Joint Photographic Experts Group ([JPEG](http://www.jpeg.org)). Since April 2015, it is officially recognized by ISO/IEC and ITU-T as a [JPEG 2000 Reference Software](http://www.itu.int/rec/T-REC-T.804-201504-I!Amd2). ## Who can use the code ? [![badge-license]][link-license] Anyone. As the OpenJPEG code is released under the [BSD 2-clause "Simplified" License][link-license], anyone can use or modify the code, even for commercial applications. The only restriction is to retain the copyright in the sources or in the binaries documentation. Of course, if you modified the code in a way that might be of interest for other users, you are encouraged to share it (through a [github pull request](https://github.com/uclouvain/openjpeg/pulls) or by filling an [issue](https://github.com/uclouvain/openjpeg/issues)) but this is not a requirement. ## How to install and use OpenJPEG ? API Documentation needs a major refactoring. Meanwhile, you can check [installation](https://github.com/uclouvain/openjpeg/wiki/Installation) instructions and [codec documentation](https://github.com/uclouvain/openjpeg/wiki/DocJ2KCodec). ## Current Status [![badge-build]][link-build] [![badge-msvc-build]][link-msvc-build] [![badge-coverity]][link-coverity] ## Who are the developers ? The library is developed and maintained by the Image and Signal Processing Group ([ISPGroup](http://sites.uclouvain.be/ispgroup/)), in the Université catholique de Louvain ([UCL](http://www.uclouvain.be/en-index.html), with the support of the [CNES](https://cnes.fr/), the [CS](http://www.c-s.fr/) company and the [intoPIX](http://www.intopix.com) company. The JPWL module has been developed by the Digital Signal Processing Lab ([DSPLab](http://dsplab.diei.unipg.it/)) of the University of Perugia, Italy ([UNIPG](http://www.unipg.it/)). ## Details on folders hierarchy * src * lib * openjp2: contains the sources of the openjp2 library (Part 1 & 2) * openjpwl: contains the additional sources if you want to build a JPWL-flavoured library. * openjpip: complete client-server architecture for remote browsing of jpeg 2000 images. * openjp3d: JP3D implementation * openmj2: MJ2 implementation * bin: contains all applications that use the openjpeg library * common: common files to all applications * jp2: a basic codec * mj2: motion jpeg 2000 executables * jpip: OpenJPIP applications (server and dec server) * java: a Java client viewer for JPIP * jp3d: JP3D applications * tcltk: a test tool for JP3D * wx * OPJViewer: gui for displaying j2k files (based on wxWidget) * wrapping * java: java jni to use openjpeg in a java program * thirdparty: thirdparty libraries used by some applications. These libraries will be built only if there are not found on the system. Note that libopenjpeg itself does not have any dependency. * doc: doxygen documentation setup file and man pages * tests: configuration files and utilities for the openjpeg test suite. All test images are located in [openjpeg-data](https://github.com/uclouvain/openjpeg-data) repository. * cmake: cmake related files * scripts: scripts for developers See [LICENSE][link-license] for license and copyright information. See [INSTALL](https://github.com/uclouvain/openjpeg/blob/master/INSTALL.md) for installation procedures. See [NEWS](https://github.com/uclouvain/openjpeg/blob/master/NEWS.md) for user visible changes in successive releases. ## API/ABI An API/ABI timeline is automatically updated [here][link-api-timeline]. OpenJPEG strives to provide a stable API/ABI for your applications. As such it only exposes a limited subset of its functions. It uses a mechanism of exporting/hiding functions. If you are unsure which functions you can use in your applications, you should compile OpenJPEG using something similar to gcc: `-fvisibility=hidden` compilation flag. See also: http://gcc.gnu.org/wiki/Visibility On windows, MSVC directly supports export/hiding function and as such the only API available is the one supported by OpenJPEG. [comment-license]: https://img.shields.io/github/license/uclouvain/openjpeg.svg "https://img.shields.io/badge/license-BSD--2--Clause-blue.svg" [badge-license]: https://img.shields.io/badge/license-BSD--2--Clause-blue.svg "BSD 2-clause \"Simplified\" License" [link-license]: https://github.com/uclouvain/openjpeg/blob/master/LICENSE "BSD 2-clause \"Simplified\" License" [badge-build]: https://travis-ci.org/uclouvain/openjpeg.svg?branch=master "Build Status" [link-build]: https://travis-ci.org/uclouvain/openjpeg "Build Status" [badge-msvc-build]: https://ci.appveyor.com/api/projects/status/github/uclouvain/openjpeg?branch=master&svg=true "Windows Build Status" [link-msvc-build]: https://ci.appveyor.com/project/detonin/openjpeg/branch/master "Windows Build Status" [badge-coverity]: https://scan.coverity.com/projects/6383/badge.svg "Coverity Scan Build Status" [link-coverity]: https://scan.coverity.com/projects/uclouvain-openjpeg "Coverity Scan Build Status" [link-api-timeline]: http://www.openjpeg.org/abi-check/timeline/openjpeg "OpenJPEG API/ABI timeline" ======================================================================== * src/bin/jpip/README ======================================================================== ======================================================================== OpenJPIP software 2.1 ReadMe OpenJPEG: http://www.openjpeg.org Written by: Kaori Hagihara UCL/SST/ICTM/ELEN February 18 2011 ======================================================================== Contents: 1. Introduction 2. License 3. System requirements 4. Implementing instructions 5. JP2 encoding instructions ---------- 1. Introduction ---------- OpenJPIP software is an implementation of JPEG 2000 Part9: Interactivity tools, APIs and protocols (JPIP). ( For more info about JPIP, check the website: http://www.jpeg.org/jpeg2000/j2kpart9.html) The current implementation uses some results from the 2KAN project (http://www.2kan.org). Version 2.1 covers: - JPT-stream (Tile) and JPP-stream (Precinct) media types - Session, channels, cache model managements - JPIP over HTTP, HTTP requests and TCP return - Indexing JPEG 2000 files - Embedding XML formatted metadata - Region Of Interest (ROI) requests - Access to JP2 files with their URL ---------- 2. License ---------- This software is released under the BSD license, anybody can use or modify the library, even for commercial applications. The only restriction is to retain the copyright in the sources or the binaries documentation. Neither the author, nor the university accept any responsibility for any kind of error or data loss which may occur during usage. ---------- 3. System requirements ---------- - FastCGI development kit (C libraries) at server (http://www.fastcgi.com) - libcURL library - Java application launcher at client - Xerces2 java XML parser on the client for accessing embedded image metadata (http://xerces.apache.org/xerces2-j) We tested this software with a virtual server running on the same Linux machine as the clients. ---------- 4. Building instructions ---------- A Makefile is available in the same directory as this README file. Simply type 'make' and it will build all the required C-executables. Concerning the java-based opj_viewer, simply type 'ant' in the corresponding directory (requires 'ant' utility of course) The documentation can be build this way (requires doxygen utility): cd doc doxygen Doxyfile ---------- 5. Usage ---------- Preliminary notes : * HTML documentation is available at http://www.openjpeg.org/jpip/doc/html * Example image is available at http://www.openjpeg.org/jpip/data/copenhague1.zip (20 Mb !) Webserver: You need a webserver running with the fastcgi module enabled and correctly configured. For Apache, add the following line to your /etc/apache2/mods-available/fastcgi.conf configuration file: FastCGIExternalServer /var/www/myFCGI -host localhost:3000 where /var/www is your DocumentRoot. Please refer to 'http://www.openjpeg.org/jpip/doc/ApacheFastCGITutorial.pdf' for more details. Server: 1. Store JP2 files in the same directory as opj_server 2. Launch opj_server from the server terminal: % spawn-fcgi -f ./opj_server -p 3000 -n For shutting down JPIP server: %GET http://hostname/myFCGI?quitJPIP Notice, http://hostname/myFCGI is the HTTP server URI (myFCGI refers to opj_server by the server setting) Requst message "quitJPIP" can be changed in Makfile, modify -DQUIT_SIGNAL=\"quitJPIP\" Client: 1. Launch image decoding server, and keep it alive as long as image viewers are open % ./opj_dec_server [portnumber (50000 by default)] You might prefer to implement this program from another directory since cache files are saved in the working directory. % mkdir cache % cd cache % ../opj_dec_server 2. Open image viewers (as many as needed) % java -jar opj_viewer.jar http://hostname/myFCGI path/filename.jp2 [hostname] [portnumber] [stateless/session] [jptstream/jppstream] [tcp/udp] ( The arguments - http://hostname/myFCGI is the HTTP server URI (myFCGI refers to opj_server by the server setting) - path/filename.jp2 is the server local path or URL of a JP2 file - host name of opj_dec_server, localhost by default - portnumber of opj_dec_server, 50000 by default - request type stateless for no caching, session (default) for caching - return media type, JPT-stream tile based stream, or JPP-stream (default) precinct based stream - auxiliary return protocol, tcp or udp (udp is not implemented yet), if not given, return data is filled in http chunk Image viewer GUI instructions: Scale up request: Enlarge the window ROI request: Select a region by mouse click and drag, then click inside the red frame of the selected region % java -jar opj_viewer_xerces.jar http://hostname/myFCGI JP2_filename.jp2 Annotate image with ROI information in XML metadata: Click button "Region Of Interest" Open a new window presenting an aligned image with a locally stored image: Click button "Image Registration" (Under Construction) 3. Quit the image decoding server through the telnet, be sure all image viewers are closed % telnet localhost 50000 quit ---------- 5. JP2 encoding instructions ---------- An example to encode a TIF image "copenhague1.tif" at resolution 4780x4050, 8bit/pixel, grayscale. % ./image_to_j2k -i copenhague1.tif -o copenhague1.jp2 -p RPCL -c [64,64] -t 640,480 -jpip -TP R options -jpip : embed index table 'cidx' box into the output JP2 file (obligation for JPIP) -TP R : partition a tile into tile parts of different resolution levels (obligation for JPT-stream)