diff --git a/README.md b/README.md index 8a22e5a..6e0a72e 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,7 @@ Open source implementation of High-throughput JPEG2000 (HTJ2K), also known as JPH, JPEG2000 Part 15, ISO/IEC 15444-15, and ITU-T T.814. Here, we are interested in implementing the HTJ2K only, supporting features that are defined in JPEG2000 Part 1 (for example, for wavelet transform, only reversible 5/3 and irreversible 9/7 are supported). -The interested reader is referred to [HTJ2K white paper](https://kakadusoftware.com/wp-content/uploads/2019/09/HTJ2K-White-Paper.pdf) for more details on HTJ2K, [this](https://kakadusoftware.com/wp-content/uploads/2019/09/icip2019.pdf) paper for the attainable performance on CPU, and [this](https://kakadusoftware.com/wp-content/uploads/2019/09/ICIP2019_GPU.pdf) paper for decoding on a GPU. - +The interested reader is referred to the [short HTJ2K white paper](http://ds.jpeg.org/whitepapers/jpeg-htj2k-whitepaper.pdf), or the [extended HTJ2K white paper](https://htj2k.com/wp-content/uploads/white-paper.pdf) for more details on HTJ2K. [This](https://kakadusoftware.com/wp-content/uploads/2019/09/icip2019.pdf) paper explores the attainable performance on CPU, and [this](https://kakadusoftware.com/wp-content/uploads/2019/09/ICIP2019_GPU.pdf) paper for decoding on a GPU. # Status # @@ -14,13 +13,18 @@ As it stands, the OpenJPH library needs documentation. The provided encoder ojph The provided command line tools ojph\_compress and ojph\_expand accepts and generated .pgm, .ppm, and .yuv. See the usage examples below. +# Web-based Demos # + +The associate site [openjph.org](https://openjph.org) serves as a blog. It currently host the [javascript](https://openjph.org/javascript/demo.html) demo of the decoder; the webpage demonstrates that the library can be compiled to javascript, and can run inside a web-browser. Any browser supporting webassembly can be used to view this webpage; examples include Firefox, Chrome, Safari, and Edge, on a desktop, mobile, or tablet. + +Another project of interest is the [openjphjs](https://github.com/chafey/openjphjs) project, developed by [Chris](https://github.com/chafey). You can see [there](https://chafey.github.com/openjphjs/test/browser/index.html) a nice online demonstration of javascript-based HTJ2K encoding/decoding, with a wealth of features and user-selectable options. # Compiling # The code employs the *cmake* tool to generate a variety of build environments. A visual studio code container is included for building using the visual studio code remote containers add in (highly recommended) -**For Linux** +## For Linux ## cd build cmake -DCMAKE_BUILD_TYPE=Release ../ @@ -28,14 +32,14 @@ the visual studio code remote containers add in (highly recommended) The generated library and executables will be in the bin folder. -**For Windows** +## For Windows ## cd build cmake ../ -G "Visual Studio 14 2015 Win64" cmake support other visual studio versions. This command generates a solution in the build folder, which can be build using visual studio. -**For macOS** +## For macOS ## You can use the "For Linux" approach above. Alternatively, you can use the Xcode project in src/apps/apps.xcodeproj, which I use. Another approach is to use cmake to generate an xcode project, in the build folder, using @@ -49,28 +53,27 @@ The generated library and executables will be in the bin folder. The library can now be compiled to javascript/wasm. For this purpose, a small wrapper file (ojph_wrapper.cpp) has been written to interface between javascript and C++; the wrapper currently supports decoding only. A small demo page demonstrating the script can be accessed [here](https://openjph.org/javascript/demo.html). -Compilation needs the [emscripten](https://emscripten.org/) tools. One way of using these tools is to install them on your machine, and activate them using +Compilation needs the [emscripten](https://emscripten.org/) tools. One way of using these tools is to install them on your machine, and activate them using - source emsdk_env.sh + source emsdk_env.sh before compilation. Alternatively, if you are a docker user, the you can launch a docker session using script provided at ```subprojects/js/emscripten-docker.sh```; this script will download a third-party docker image that has the emscripten tools integrated in it -- Thanks to [Chris](https://github.com/chafey) for the suggesting and providing these tools. The javascript decoder can be compiled using - cd subprojects/js/build - emmake cmake .. - make - + cd subprojects/js/build + emmake cmake .. + make The compilation creates libopenjph.js and libopenjph.wasm in subprojects/js/html folder. That html folder also has the demo webpage index.html and a compressed image test.j2c which the script in index.html decodes. To run the demo webpage on your machine, you need a webserver running on the machine -- Due to security reasons, javascript engines running in a browser cannot access local files on the machine. You can use the ```emrun``` command, provided with the emscripten tools, by issuing the command - emrun index.html + emrun index.html from inside the html folder; the default port is 6931. Alternatively, a simple python webserver can be run using - python -m SimpleHTTPServer 8000 + python -m SimpleHTTPServer 8000 also from inside the html folder. Here, 8000 is the port number at which the webserver will be listening. The webpage can then be accessed by open 127.0.0.1:8000 in you browser. Any browser supporting webassembly can be used to view this webpage; examples include Firefox, Chrome, Safari, and Edge, on a desktop, mobile, or tablet. @@ -99,7 +102,7 @@ Here are some usage examples: ojph_expand -i input_file.j2c -o output_file.ppm ojph_expand -i input_file.j2c -o output_file.yuv -**Notes**: +**Notes**: * Issuing ojph\_compress or ojph\_expand without arguments prints a short usage statement. * In reversible compression, quantization is not supported. @@ -107,9 +110,6 @@ Here are some usage examples: * When the source is a .yuv file, use -downsamp {1,1} for 4:4:4 sources. For 4:2:2 downsampling, specify -downsamp {1,1},{2,1}, and for 4:2:0 subsampling specify -downsamp {1,1},{2,2}. The source must have already been downsampled (i.e., OpenJPH does not downsample the source before compression, but can compress downsampled sources). * In Kakadu, pairs of data in command line arguments represent columns,rows. Here, a pair represents x,y information. -# Related # +# The standard # The standard is available [here](https://www.itu.int/rec/T-REC-T.814/en). It is currently free of charge; I do not know if this is temporary or permanent -- **Update 25/12/2019**: it is no longer available free of charge. - -The associate site [openjph.org](https://openjph.org) serves as a blog. It currently host the [javascript](https://openjph.org/javascript/demo.html) demo of the decoder; the webpage demonstrates that the library can be compiled to javascript, and can run inside a web-browser. Any browser supporting webassembly can be used to view this webpage; examples include Firefox, Chrome, Safari, and Edge, on a desktop, mobile, or tablet. -