JasPer ====== JPEG-2000 image codec library and tools .. toctree:: :maxdepth: 1 :caption: Contents: Overview -------- `JasPer `_ is a library and tools for reading and writing JPEG-2000 (JP2) image files. JasPer provides a complete implementation of the JPEG-2000 Part-1 standard (ISO/IEC 15444-1). .. note:: We provide JasPer installation that is optimised and more reliable than the system-wide one. Therefore, we recommend using our installation instead of the system-wide one (see below). Available versions ------------------ To view available ``jasper`` versions: .. code-block:: bash module avail jasper Build recipes and configuration details are maintained in our GitLab repository: * `Build Recipes `_ Build optimisations ------------------- Our JasPer installations are optimised for maximum performance on Discoverer's hardware. We use the recent :doc:`llvm` compilers to build the JasPer library code, which are the default compilers on Discoverer Petascale Supercomputer. Compiler optimisations: - **Link Time Optimisation (LTO)**: Full LTO (``-flto=full``) is enabled for both compilation and linking, allowing cross-module optimisations that significantly improve performance. - **CPU-Specific Optimisations**: - ``-march=native``: Optimises for the native CPU architecture, enabling all available instruction sets - ``-mtune=native``: Tunes the generated code specifically for the target CPU - **Position Independent Code**: ``-fPIC`` is used to enable shared library support. Linker optimisations: - **LLD Linker**: We use LLVM's LLD linker (``-fuse-ld=lld``) for faster linking and better optimisation support. - **LTO at Link Time**: ``-flto=full -Wl,--lto-O3`` enables full link-time optimisation with optimisation level 3, allowing the linker to perform whole-program optimisations. Build configuration: - **Release Build**: ``CMAKE_BUILD_TYPE=Release`` ensures all optimisations are enabled. - **C++ Support**: ``DJAS_ENABLE_CXX=ON`` enables C++ interface support. - **Shared Libraries**: ``DJAS_ENABLE_SHARED=ON`` builds shared libraries for dynamic linking. - **Multi-threading**: ``DJAS_ENABLE_MULTITHREADING_SUPPORT=ON`` enables multi-threaded image processing support. - **Strict Mode**: ``DJAS_STRICT=ON`` enables strict compliance checking for better standards compliance. Build system: - **Build Tool**: Ninja build system is used for fast parallel builds. - **Parallel Compilation**: Builds use 12 parallel compilation jobs for efficient resource utilisation. - **Testing**: All builds are tested using the comprehensive test suite (ctest) before installation, ensuring correctness and reliability. - **External Build Directory**: The build is performed in an external directory to comply with JasPer's build system requirements. These optimisations ensure that our JasPer installation provides the fastest possible image processing performance for JPEG-2000 files on Discoverer, while maintaining full compatibility with the standard JasPer API. Compiler support ---------------- .. warning:: For now we will support only LLVM builds of JasPer. No other builds will be officially supported. Supported builds ---------------- Production builds: .. code-block:: bash module avail jasper Available libraries ------------------- JasPer provides the libjasper shared library that is installed by default: ``libjasper.so`` - JPEG-2000 image codec library This library implements the JPEG-2000 Part-1 standard (ISO/IEC 15444-1), providing high-quality image compression and decompression with support for various image formats. - **Header file**: ``jasper/jasper.h`` - **Link flag**: ``-ljasper`` - **pkg-config**: ``jasper`` .. note:: The library uses optimised implementations and can be used in both C and C++ applications. Library variants ---------------- The libjasper library is available as a shared (``.so``) library. The Environment Modules automatically configure the appropriate paths for dynamic linking, which is the recommended approach for HPC environments. Shared libraries (recommended): - ``libjasper.so`` is used by default - Automatically configured when loading the module - Recommended for HPC environments Linking your application ------------------------ After loading the ``jasper`` module, the environment variables are automatically configured. You can link your application using one of the following methods: Method 1: Using environment variables (recommended) .. code-block:: bash # Load the module first module load jasper/ # Link against libjasper - C code gcc -o myapp myapp.c $CFLAGS $LDFLAGS -ljasper clang -o myapp myapp.c $CFLAGS $LDFLAGS -ljasper # Link against libjasper - C++ code g++ -o myapp myapp.cpp $CXXFLAGS $LDFLAGS -ljasper clang++ -o myapp myapp.cpp $CXXFLAGS $LDFLAGS -ljasper Method 2: Using pkg-config .. code-block:: bash # Load the module first module load jasper/ # Link against libjasper - C code gcc -o myapp myapp.c $(pkg-config --cflags --libs jasper) clang -o myapp myapp.c $(pkg-config --cflags --libs jasper) # Link against libjasper - C++ code g++ -o myapp myapp.cpp $(pkg-config --cflags --libs jasper) clang++ -o myapp myapp.cpp $(pkg-config --cflags --libs jasper) Method 3: Manual linking .. code-block:: bash # Load the module first module load jasper/ # Link against libjasper - C code gcc -o myapp myapp.c -I$JASPER_ROOT/include -L$JASPER_ROOT/lib64 -ljasper clang -o myapp myapp.c -I$JASPER_ROOT/include -L$JASPER_ROOT/lib64 -ljasper # Link against libjasper - C++ code g++ -o myapp myapp.cpp -I$JASPER_ROOT/include -L$JASPER_ROOT/lib64 -ljasper clang++ -o myapp myapp.cpp -I$JASPER_ROOT/include -L$JASPER_ROOT/lib64 -ljasper .. note:: The Environment Modules automatically set ``CFLAGS``, ``CXXFLAGS``, and ``LDFLAGS`` when you load the module. Using these variables is the recommended approach as they remain correct even if the module path changes. Replacing the system-wide jasper installation --------------------------------------------- To use the ``libjasper.so`` library from our installation instead of relying on the system-wide installation: .. code-block:: bash module load jasper/ ./your_program # will automatically use libjasper.so from jasper installation This way your executable will use the ``jasper`` library from our installation instead of the system-wide one. Command-line utilities ---------------------- JasPer provides a comprehensive set of command-line utilities for working with JPEG-2000 image files. After loading the ``jasper`` module, these utilities are available in your ``PATH``. Main conversion tool: ``jasper`` - Image format conversion tool The primary utility for converting images between various formats, including JPEG-2000 (JP2), JPEG, PNM, BMP, RAS, and PGX formats. - Converts images to and from JPEG-2000 format - Supports multiple input and output formats - Provides compression quality control - Supports various image colour spaces Information and analysis tools: ``imginfo`` - Image information display Displays detailed information about image files, including dimensions, colour space, bit depth, and format-specific metadata. Useful for inspecting image properties before processing. - Shows image dimensions (width, height) - Displays colour space information - Reports bit depth and sample precision - Lists format-specific metadata ``imgcmp`` - Image comparison tool Compares two images pixel-by-pixel and reports differences. Useful for verifying image processing operations, testing compression quality, and validating image transformations. - Performs pixel-by-pixel comparison - Reports difference statistics - Useful for quality assessment - Supports various comparison metrics Viewing tool: ``jiv`` - JPEG-2000 image viewer A simple image viewer specifically designed for JPEG-2000 files. Allows quick visual inspection of JPEG-2000 images without requiring conversion to other formats. - Views JPEG-2000 images directly - Simple command-line interface - Useful for quick image inspection Example usage: .. code-block:: bash # Load the module module load jasper/ # Convert an image to JPEG-2000 format jasper -t jp2 -f myimage.png -F myimage.jp2 # Display image information imginfo myimage.jp2 # Compare two images imgcmp image1.jp2 image2.jp2 # View a JPEG-2000 image jiv myimage.jp2 # Convert from JPEG-2000 to PNG jasper -t pnm -f myimage.jp2 -F myimage.pnm # Then convert PNM to PNG using ImageMagick or similar .. warning:: When processing large images or multiple files, use Slurm batch jobs to execute these utilities on compute nodes rather than login nodes. Getting help ------------ For additional assistance: * See the :doc:`help` documentation