DOCSEARCHbyAlgolia
Submit Docs

OpenJPEG Documentation

repository·master·Indexed 19 days ago

https://github.com/uclouvain/openjpeg

OpenJPEG is an open-source JPEG 2000 codec written in C and serves as the official ISO/IEC and ITU-T recognized JPEG 2000 Reference Software. It includes the libopenjp2 library for encoding and decoding, as well as command-line utilities such as opj_compress for converting images to JPEG2000, opj_decompress for decoding, and opj_dump for file inspection. The project also provides the openjpip client-server architecture for remote image browsing and JNI bindings for Java.

Tokens
24.7K
Snippets
81
Records
127
Agent score
73%

What's inside OpenJPEG

  1. What is OpenJPEG?

    master

    OpenJPEG is an open-source JPEG 2000 codec implemented in C. It is designed to support the JPEG 2000 still-image compression standard. Beyond the core codec, the project includes support for various features and formats such as:

    • JP2 and MJ2: JPEG 2000 and Motion JPEG 2000 file formats.
    • JPIP Indexing: Tools for the JPEG 2000 Interactive Protocol.
    • JPWL-tools: Tools for error-resilience.
    • Java-viewer: A viewer for .j2k images.

  2. Understand the OPJViewer interface and features

    master

    OPJViewer is a GUI application used to open and display the information and image content of J2K, JP2, and MJ2 files. The interface is divided into three functional panels:

    1. Browsing Pane

    Displays the hierarchy of markers or boxes. For each entry, it shows:

    • The marker/box short name (Hex code).
    • The marker/box long name.
    • Position information: startbyte > stopbyte.
    • Length information: inner_length + marker/box sign length (total length).
    • Additional metadata specific to the marker/box type.

    2. Viewing Pane

    Displays the decoded image from the JPEG 2000 file. It is tested to display images up to 4000x2000 pixels (requires several GB of RAM).

    3. Log/Peek Pane

    This pane switches between two modes:

    • Log Panel: Reports debugging information from the wxWidgets GUI and the OpenJPEG library.
    • Peek Pane: Provides a hex and ASCII view of the specific codestream/file portion currently selected in the browsing pane.

    Limitations:

    • For MJ2 files, rendering is currently limited to Black & White (B/W).

  3. Explore the OpenJPEG repository structure

    master

    The repository is organized into several key directories:

    • src/lib/openjp2: Contains the core openjp2 library sources (Part 1 & 2).
    • src/lib/openjpip: Contains the openjpip client-server architecture for remote JPEG 2000 image browsing.
    • src/bin: Contains applications using the library:
      • common: Shared files for all applications.
      • jp2: Basic codec applications.
      • jpip: OpenJPIP server and decoder applications.
      • wx/OPJViewer: GUI for displaying .j2k files (requires wxWidgets).
    • wrapping/java: JNI bindings for using OpenJPEG in Java programs.
    • thirdparty: External libraries used by applications (built only if not found on the system).
    • doc: Doxygen configuration and man pages.
    • tests: Test suite configuration and utilities. Note that test images are stored in the separate openjpeg-data repository.
    • cmake: CMake build configuration files.

  5. Understand the OPJViewer browsing pane hierarchy

    master

    The browsing pane presents the file structure using a tree-like hierarchy of markers and boxes. Each entry includes technical metadata about its location and size within the file.

    Example structure:

    filename
|
|_ #000: Marker/Box short name (Hex code)
|  |
|  |_ *** Marker/Box long name ***
|  |_ startbyte > stopbyte, inner_length + marker/box sign length (total length)
|  |_ Additional info, depending on the marker/box type
|  |_ ...

  6. Understand OpenJPEG API/ABI stability

    master

    OpenJPEG aims to provide a stable API/ABI by exposing only a limited subset of its functions through an export/hiding mechanism.

    To ensure you are only using supported functions in your applications, it is recommended to compile OpenJPEG using the -fvisibility=hidden flag (for GCC). On Windows, MSVC handles function visibility directly, and the available API is restricted to the functions explicitly supported by OpenJPEG.

    You can track the API/ABI stability via the official timeline: http://www.openjpeg.org/abi-check/timeline/openjpeg.

  7. License and usage rights

    master

    OpenJPEG is released under the BSD 2-clause "Simplified" License.

    Key terms:

    • Anyone can use, modify, or distribute the code, including for commercial applications.
    • Requirement: You must retain the copyright notice in the sources or in the binaries/documentation.
    • Modifications are encouraged to be shared via GitHub pull requests or issues, but are not required.

  8. Enable CPU-specific optimizations (SSE4.1 and AVX2)

    master

    OpenJPEG supports SSE4.1 and AVX2 instruction sets for Intel/AMD processors. Enabling these will result in faster performance but the resulting binaries will only run on compatible CPUs. Use the CMAKE_C_FLAGS flag with gcc or clang to enable them.

    • SSE4.1: -DCMAKE_C_FLAGS="-O3 -msse4.1 -DNDEBUG"
    • AVX2: -DCMAKE_C_FLAGS="-O3 -mavx2 -DNDEBUG" (Note: AVX2 implies SSE4.1)
    • Native Optimization: To optimize specifically for the machine you are currently compiling on, use -DCMAKE_C_FLAGS="-O3 -march=native -DNDEBUG".
    # Enable AVX2 optimizations
cmake -DCMAKE_C_FLAGS="-O3 -mavx2 -DNDEBUG" ..

  9. Use bundled 3rd party libraries for OpenJPEG builds

    master

    The thirdparty/ directory contains convenient copies of external libraries (such as PNG and ZLIB) provided to simplify the OpenJPEG build process on systems where these libraries are not easily accessible (typically non-UNIX environments).

    Important Warnings:

    • Not Recommended: OpenJPEG does not recommend using these bundled libraries over your system-installed libraries.
    • No Guarantee: OpenJPEG does not guarantee that these bundled libraries will work correctly for your specific environment.

  11. Build OpenJPEG for MacOS and Windows (Visual Studio)

    master

    You can use CMake to generate project files for specific IDEs. Use cmake --help to see available generators for your platform.

    Windows (Visual Studio)

    To create Visual Studio solution (.sln) and project files (.vcxproj), use the -G flag.

    For 64-bit applications: Use the Win64 generator (e.g., Visual Studio 14 2015 Win64).

    Using the cl compiler directly (NMake):

    cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE:string="Release" -DBUILD_SHARED_LIBS:bool=on -DCMAKE_INSTALL_PREFIX:path="%USERPROFILE%" -DCMAKE_LIBRARY_PATH:path="%USERPROFILE%" -DCMAKE_INCLUDE_PATH:path="%USERPROFILE%\include" ..

    MacOS

    If the build fails on MacOS, try adding the following flag to your CMake command: -DCMAKE_OSX_ARCHITECTURES:STRING=i386

    # Example for Visual Studio 14 2015 64-bit
cmake -G "Visual Studio 14 2015 Win64" -DCMAKE_BUILD_TYPE:string="Release" -DBUILD_SHARED_LIBS:bool=on -DCMAKE_INSTALL_PREFIX:path="%USERPROFILE%" -DCMAKE_LIBRARY_PATH:path="%USERPROFILE%" -DCMAKE_INCLUDE_PATH:path="%USERPROFILE%\include" ..

  12. Build OpenJPEG on UNIX/Linux, MacOS, or Windows (Cygwin/MinGW)

    master

    OpenJPEG uses CMake for its build system. To build the library from source on UNIX-like systems or Windows environments like Cygwin or MinGW, follow these steps:

    1. Create a build directory and enter it.
    2. Run cmake with the Release build type.
    3. Run make to compile.

    Compiled binaries will be located in the bin directory. To install the library to your system, run make install with root privileges.

    mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

# To install
sudo make install
make clean