feat(openjpeg): Write .j2c by adding HTJ2K Encoding using the OpenJPH library. (#4699)

OIIO did already have a decompressor for HTJ2K via the OpenJpeg library,
but nothing for encoding. This adds the encoder using the OpenJPH
library, which will be needed for the HTJ2K encoding for OpenEXR too.

This is a merge with the OpenJpeg plugin, the reader will attempt to
use the OpenJPH library (if found) to read the input file, if it cannot
read it, it will fall back on OpenJpeg to read it. For writing with the
OpenJpeg library, if the compression flag is set to htj2k or the file
extension is j2c the OpenJPH library will be called to write out the
file.

If you want to do a lossy encode you can do it with:

```
oiiotool -i INPUTFILE --attrib jph:qstep 0.03 -o OUTPUTFILE.j2c

oiiotool -i INPUTFILE --compression htj2k --attrib jph:qstep 0.03 -o
OUTPUTFILE.j2k
```

Other options include:

```oiiotool -i INPUTFILE --compression htj2k --attrib jph:qstep 0.03
--attrib jph:num_decomps 3 --attrib jph:block_size 32,32 --attrib
jph:prog_order CPRL --attrib jph:precincts 128,128,256,256 -o
OUTPUTFILE.j2c
```

Added a htj2k test, it tests encoding a dox and a jpeg file, both
lossless and lossy.

---------

Signed-off-by: Sam.Richards@taurich.org <Sam.Richards@taurich.org>

Author: richardssam

src/cmake/add_oiio_plugin.cmake

@@ -11,16 +11,17 @@
 #                   [ NAME targetname ... ]
 #                   [ SRC source1 ... ]
 #                   [ INCLUDE_DIRS include_dir1 ... ]
+#                   [ LINK_DIRECTORIES link_dir1 ... ]
 #                   [ LINK_LIBRARIES external_lib1 ... ]
 #                   [ COMPILE_OPTIONS -Wflag ... ]
 #                   [ DEFINITIONS FOO=bar ... ])
 #
 # The plugin name can be specified with NAME, otherwise is inferred from the
 # subdirectory name. The source files of the binary can be specified with
 # SRC, otherwise are inferred to be all the .cpp files within the
-# subdirectory. Optional compile DEFINITIONS, private INCLUDE_DIRS, and
-# private LINK_LIBRARIES may also be specified. The source is automatically
-# linked against OpenImageIO.
+# subdirectory. Optional compile DEFINITIONS, private INCLUDE_DIRS, private 
+# LINK_DIRECTORIES, and private LINK_LIBRARIES may also be specified. 
+# The source is automatically linked against OpenImageIO.
 #
 # The plugin may be disabled individually using any of the usual
 # check_is_enabled() conventions (e.g. -DENABLE_<format>=OFF).
@@ -35,7 +36,7 @@
 # be handed off too the setup of the later OpenImageIO target.
 #
 macro (add_oiio_plugin)
-    cmake_parse_arguments (_plugin "" "NAME" "SRC;INCLUDE_DIRS;LINK_LIBRARIES;COMPILE_OPTIONS;DEFINITIONS" ${ARGN})
+    cmake_parse_arguments (_plugin "" "NAME" "SRC;INCLUDE_DIRS;LINK_DIRECTORIES;LINK_LIBRARIES;COMPILE_OPTIONS;DEFINITIONS" ${ARGN})
        # Arguments: <prefix> <options> <one_value_keywords> <multi_value_keywords> args...
     get_filename_component (_plugin_name ${CMAKE_CURRENT_SOURCE_DIR} NAME_WE)
     if (NOT _plugin_NAME)
@@ -64,6 +65,7 @@ macro (add_oiio_plugin)
             set (format_plugin_definitions ${format_plugin_definitions} ${_plugin_DEFINITIONS} PARENT_SCOPE)
             set (format_plugin_compile_options ${format_plugin_compile_options} ${_plugin_COMPILE_OPTIONS} PARENT_SCOPE)
             set (format_plugin_include_dirs ${format_plugin_include_dirs} ${_plugin_INCLUDE_DIRS} PARENT_SCOPE)
+            set (format_plugin_lib_dirs ${format_plugin_lib_dirs} ${_plugin_LINK_DIRECTORIES} PARENT_SCOPE)
             set (format_plugin_libs ${format_plugin_libs} ${_plugin_LINK_LIBRARIES} PARENT_SCOPE)
         else ()
             # # Get the name of the current directory and use it as the target name.
@@ -74,6 +76,8 @@ macro (add_oiio_plugin)
                                         OpenImageIO_EXPORTS)
             target_compile_options (${_plugin_NAME} PRIVATE ${_plugin_COMPILE_OPTIONS})
             target_include_directories (${_plugin_NAME} BEFORE PRIVATE ${_plugin_INCLUDE_DIRS})
+            target_link_directories (${_plugin_NAME} PUBLIC OpenImageIO
+                                                     PRIVATE ${_plugin_LINK_DIRECTORIES})
             target_link_libraries (${_plugin_NAME} PUBLIC OpenImageIO
                                                    PRIVATE ${_plugin_LINK_LIBRARIES})
             set_target_properties (${_plugin_NAME} PROPERTIES PREFIX "" FOLDER "Plugins")

src/cmake/externalpackages.cmake

@@ -176,6 +176,8 @@ checked_find_package (OpenJPEG VERSION_MIN 2.0
 # Note: Recent OpenJPEG versions have exported cmake configs, but we don't
 # find them reliable at all, so we stick to our FindOpenJPEG.cmake module.
 
+checked_find_package (OpenJPH VERSION_MIN 0.21)
+
 checked_find_package (OpenVDB
                       VERSION_MIN  9.0
                       DEPS         TBB

src/cmake/modules/FindOpenJPEG.cmake

@@ -17,6 +17,46 @@ include (FindPackageHandleStandardArgs)
 include (FindPackageMessage)
 include (SelectLibraryConfigurations)
 
+
+
+if(DEFINED OPENJPEG_ROOT)
+    set(_openjpeg_pkgconfig_path "${OPENJPEG_ROOT}/lib/pkgconfig")
+    if(EXISTS "${_openjpeg_pkgconfig_path}")
+        set(ENV{PKG_CONFIG_PATH} "${_openjpeg_pkgconfig_path}:$ENV{PKG_CONFIG_PATH}")
+    endif()
+endif()
+
+
+find_package(PkgConfig QUIET)
+if(PKG_CONFIG_FOUND)
+    pkg_check_modules(OPENJPEG_PC QUIET openjpeg)
+endif()
+
+if(OPENJPEG_PC_FOUND)
+    set(OPENJPEG_FOUND TRUE)
+    set(OPENJPEG_VERSION ${OPENJPEG_PC_VERSION})
+    set(OPENJPEG_INCLUDES ${OPENJPEG_PC_INCLUDE_DIRS})
+    set(OPENJPEG_LIBRARIES ${OPENJPEG_PC_LIBRARIES})
+    if(NOT OPENJPEG_FIND_QUIETLY)
+        FIND_PACKAGE_MESSAGE(OPENJPEG
+            "Found OPENJPEG via pkg-config: v${OPENJPEG_VERSION} ${OPENJPEG_LIBRARIES}"
+            "[${OPENJPEG_INCLUDES}][${OPENJPEG_LIBRARIES}]"
+        )
+    endif()
+else()
+    set(OPENJPEG_FOUND FALSE)
+    set(OPENJPEG_VERSION 0.0.0)
+    set(OPENJPEG_INCLUDES "")
+    set(OPENJPEG_LIBRARIES "")
+    if(NOT OPENJPEG_FIND_QUIETLY)
+        FIND_PACKAGE_MESSAGE(OPENJPEG
+            "Could not find OPENJPEG via pkg-config"
+            "[${OPENJPEG_INCLUDES}][${OPENJPEG_LIBRARIES}]"
+        )
+    endif()
+endif()
+
+
 macro (PREFIX_FIND_INCLUDE_DIR prefix includefile libpath_var)
   string (TOUPPER ${prefix}_INCLUDE_DIR tmp_varname)
   find_path(${tmp_varname} ${includefile}

src/cmake/modules/FindOpenJPH.cmake

@@ -0,0 +1,57 @@
+# Copyright Contributors to the OpenImageIO project.
+# SPDX-License-Identifier: Apache-2.0
+# https://github.com/AcademySoftwareFoundation/OpenImageIO
+
+# Module to find OPENJPH.
+#
+# This module will first look into the directories defined by the variables:
+#   - OPENJPH_ROOT
+#
+# This module defines the following variables:
+#
+# OPENJPH_INCLUDES    - where to find ojph_arg.h
+# OPENJPH_LIBRARIES   - list of libraries to link against when using OPENJPH.
+# OPENJPH_FOUND       - True if OPENJPH was found.
+# OPENJPH_VERSION     - Set to the OPENJPH version found
+include (FindPackageHandleStandardArgs)
+include (FindPackageMessage)
+include (SelectLibraryConfigurations)
+
+if(DEFINED OPENJPH_ROOT)
+    set(_openjph_pkgconfig_path "${OPENJPH_ROOT}/lib/pkgconfig")
+    if(EXISTS "${_openjph_pkgconfig_path}")
+        set(ENV{PKG_CONFIG_PATH} "${_openjph_pkgconfig_path}:$ENV{PKG_CONFIG_PATH}")
+    endif()
+endif()
+
+
+find_package(PkgConfig QUIET)
+if(PKG_CONFIG_FOUND)
+    pkg_check_modules(OPENJPH_PC QUIET openjph)
+endif()
+
+if(OPENJPH_PC_FOUND)
+    set(OPENJPH_FOUND TRUE)
+    set(OPENJPH_VERSION ${OPENJPH_PC_VERSION})
+    set(OPENJPH_INCLUDES ${OPENJPH_PC_INCLUDE_DIRS})
+    set(OPENJPH_LIBRARY_DIRS ${OPENJPH_PC_LIBDIR})
+    set(OPENJPH_LIBRARIES ${OPENJPH_PC_LIBRARIES})
+
+    if(NOT OPENJPH_FIND_QUIETLY)
+        FIND_PACKAGE_MESSAGE(OPENJPH
+            "Found OPENJPH via pkg-config: v${OPENJPH_VERSION} ${OPENJPH_LIBRARIES}"
+            "[${OPENJPH_INCLUDES}][${OPENJPH_LIBRARIES}]"
+        )
+    endif()
+else()
+    set(OPENJPH_FOUND FALSE)
+    set(OPENJPH_VERSION 0.0.0)
+    set(OPENJPH_INCLUDES "")
+    set(OPENJPH_LIBRARIES "")
+    if(NOT OPENJPH_FIND_QUIETLY)
+        FIND_PACKAGE_MESSAGE(OPENJPH
+            "Could not find OPENJPH via pkg-config"
+            "[${OPENJPH_INCLUDES}][${OPENJPH_LIBRARIES}]"
+        )
+    endif()
+endif()

src/cmake/testing.cmake

@@ -274,6 +274,9 @@ macro (oiio_add_all_tests)
     oiio_add_tests (jpeg2000
                     FOUNDVAR OPENJPEG_FOUND
                     IMAGEDIR oiio-images URL "Recent checkout of OpenImageIO-images")
+    oiio_add_tests (htj2k
+                    FOUNDVAR OPENJPH_FOUND
+                    IMAGEDIR oiio-images URL "Recent checkout of OpenImageIO-images")
     oiio_add_tests (jpeg2000-j2kp4files
                     FOUNDVAR OPENJPEG_FOUND
                     IMAGEDIR j2kp4files_v1_5

src/doc/builtinplugins.rst

@@ -1143,6 +1143,11 @@ JPEG-2000 is not yet widely used, so OpenImageIO's support of it is
 preliminary.  In particular, we are not yet very good at handling the
 metadata robustly.
 
+Optionally this plugin can be built with OpenJPH support, which is a
+JPEG-2000 encoder/decoder that is faster than OpenJPEG, and supports the
+High Throughput JPEG2000 (HTJ2K) format (Jpeg2000 Part 15). If OpenJPH is not available, the
+OpenJPEG library will be used instead but only for decoding. OpenJPH is available at  https://github.com/aous72/OpenJPH .
+
 **Attributes**
 
 .. list-table::
@@ -1186,6 +1191,9 @@ attributes are supported:
      - ptr
      - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for
        example by reading from memory rather than the file system.
+  
+If OpenJPH is installed, the reader will attempt to read the file first with 
+the OpenJPH library, and if that fails, it will fall back to the OpenJPEG library.
 
 **Configuration settings for JPEG-2000 output**
 
@@ -1215,14 +1223,52 @@ control aspects of the writing itself:
        for output rather than being assumed to be associated and get automatic
        un-association to store in the file.
 
+If OpenJPH is installed, and the file extension is :file:`.j2c`, or if the -``compression`` flag is set to ``"htj2k"``, the
+writer will attempt to write the file with the OpenJPH library, and the following flags will be available:
+
+.. list-table::
+   :widths: 30 10 65
+   :header-rows: 1
+
+   * - Output Configuration Attribute
+     - Type
+     - Meaning
+   * - ``jph:bit_depth``
+     - int
+     - The output bitdepth of the file.
+   * - ``jph:num_decomps``
+     - int
+     - (5) number of decompositions.
+   * - ``jph:block_size``
+     - string
+     - The output block size, defaults to 64,64   
+   * - ``jph:prog_order``
+     - string
+     - (RPCL) is the progression order, and can be one of:
+               LRCP, RLCP, RPCL, PCRL, CPRL. These determine the sequence in which the image data is processed and transmitted. The letters stand for:
+        R: Resolution
+        P: position
+        C: component
+        L: Layer
+        RPCL is common for applications where resolution scalability is important.
+   * - ``jph:precincts``
+     - string
+     -   x,y,x,y,...,x,y where x,y is the precinct size
+               starting from the coarsest resolution; the last precinct
+               is repeated for all finer resolutions
+   * - ``jph:qstep``
+     - float
+     - If supplied, is the quantization step size for lossy compression; 
+       quantization steps size for all subbands are derived from this value. Valid values can be from 0.00001 to 0.5.
+       If not used, the encoder will be lossless.
+
+
 **Custom I/O Overrides**
 
 JPEG-2000 input and output both support the "custom I/O" feature via the
 special ``"oiio:ioproxy"`` attributes (see Sections
 :ref:`sec-imageoutput-ioproxy` and :ref:`sec-imageinput-ioproxy`) as well as
 the `set_ioproxy()` methods.
-
-
 |
 
 .. _sec-bundledplugins-jpegxl:

src/jpeg2000.imageio/CMakeLists.txt

@@ -3,10 +3,24 @@
 # https://github.com/AcademySoftwareFoundation/OpenImageIO
 
 if (OPENJPEG_FOUND)
-    add_oiio_plugin (jpeg2000input.cpp jpeg2000output.cpp
-                     INCLUDE_DIRS ${OPENJPEG_INCLUDES}
-                     LINK_LIBRARIES ${OPENJPEG_LIBRARIES}
-                     DEFINITIONS "USE_OPENJPEG")
+    set(_jpeg2000_includes ${OPENJPEG_INCLUDES})
+    set(_jpeg2000_lib_dirs ${OPENJPEG_LIBRARY_DIRS})
+    set(_jpeg2000_libs ${OPENJPEG_LIBRARIES})
+    set(_jpeg2000_defs "USE_OPENJPEG")
+
+    if (OPENJPH_FOUND)
+        list(APPEND _jpeg2000_includes ${OPENJPH_INCLUDES})
+        list(APPEND _jpeg2000_lib_dirs ${OPENJPH_LIBRARY_DIRS})
+        list(APPEND _jpeg2000_libs ${OPENJPH_LIBRARIES})
+        list(APPEND _jpeg2000_defs "USE_OPENJPH")
+    endif()
+
+    add_oiio_plugin(jpeg2000input.cpp jpeg2000output.cpp
+        INCLUDE_DIRS ${_jpeg2000_includes}
+        LINK_DIRECTORIES ${_jpeg2000_lib_dirs}
+        LINK_LIBRARIES ${_jpeg2000_libs}
+        DEFINITIONS ${_jpeg2000_defs}
+    )
 else()
     message (WARNING "Jpeg-2000 plugin will not be built")
 endif()