Merge pull request #3 from leftfield-geospatial/feature-clip_round_12…

…bit_jpeg

Feature clip round 12bit jpeg

.github/workflows/install-test-conda-forge.yml

@@ -32,7 +32,7 @@ jobs:
     - name: Install package
       run: |
         conda info
-        conda install homonim>=0.3.2
+        conda install homonim>=0.4.0
         conda list
 
     - name: Run CLI fusion test

.github/workflows/run-integration-tests.yml

@@ -30,7 +30,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install pytest pytest-xdist
-        python -m pip install rasterio opencv-python numpy click tqdm pyyaml cloup tabulate
+        python -m pip install rasterio opencv-python-headless numpy click tqdm pyyaml cloup tabulate
 
     - name: Test with pytest
       timeout-minutes: 5

.github/workflows/run-unit-tests.yml

@@ -34,7 +34,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install flake8 pytest pytest-xdist pytest-cov
-        python -m pip install rasterio opencv-python numpy tabulate click tqdm pyyaml cloup
+        python -m pip install rasterio opencv-python-headless numpy tabulate click tqdm pyyaml cloup
 
     - name: Lint with flake8
       run: |
@@ -49,7 +49,7 @@ jobs:
         python -m pytest -n auto --cov=homonim --cov-report=term-missing --cov-report=xml:coverage.xml ./tests
 
     - name: Upload coverage
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         fail_ci_if_error: false
         files: ./coverage.xml

README.rst

@@ -30,24 +30,21 @@ See the documentation site for more detail: https://homonim.readthedocs.io/.
 Installation
 ------------
 
-``homonim`` is available as a python 3 package, via ``pip`` and ``conda``.
+``homonim`` is available as a python 3 package, via `pip <https://pip.pypa.io/>`_ or `conda <https://docs.conda.io/projects/miniconda>`_.
 
-conda
-~~~~~
-
-Under Windows, using ``conda`` is the easiest way to resolve binary dependencies. The
-`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ installation provides a minimal ``conda``.
+pip
+~~~
 
 .. code:: shell
 
-   conda install -c conda-forge homonim
+   pip install homonim
 
-pip
-~~~
+conda
+~~~~~
 
 .. code:: shell
 
-   pip install homonim
+   conda install -c conda-forge homonim
 
 .. install_end
 

docs/background.rst

@@ -53,6 +53,5 @@ The minimum *kernel shape* is *model* dependent.  For the two parameter :attr:`~
 
 Kernel shape can be specified with the :option:`--kernel-shape <homonim-fuse --kernel-shape>` option via the command line; or with the corresponding argument in the :meth:`homonim.RasterFuse.process` API.
 
-
 .. |geedim| replace:: ``geedim``
 .. _geedim: https://github.com/leftfield-geospatial/geedim

docs/cli.rst

@@ -1,8 +1,8 @@
 Command line interface
-----------------------
+======================
 
 Getting started
-^^^^^^^^^^^^^^^
+---------------
 
 .. include:: ../README.rst
     :start-after: cli_start
@@ -11,7 +11,7 @@ Getting started
 .. _cli_running_examples:
 
 Running examples
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
 
 The examples that follow use the ``homonim`` test images.  You can get these by downloading the repository directly:
 
@@ -37,7 +37,7 @@ The commands that follow use relative paths, and should be run from *<homonim ro
 
 
 Basic fusion and comparison
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The *gain-blk-offset* model and kernel shape of 5 x 5 pixels are the default fusion settings and work reasonably well for a variety of problems.  Here we specify these settings to correct the test aerial images with the Sentinel-2 reference.
 
@@ -81,7 +81,7 @@ It is possible to combine the above *fuse* and *compare* commands, using the :op
 
 
 Band matching
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 ``homonim`` automatically matches *source* to *reference* spectral bands when these images are either RGB or have ``center_wavelength`` metadata (as is the case with the ``homonim`` test data).  Subsets of *source* and/or *reference* bands to use for matching can be specified with the :option:`--src-band <homonim-fuse --src-band>` and :option:`--ref-band <homonim-fuse --ref-band>` options.
 
@@ -122,19 +122,34 @@ Let's repeat the previous example to see how this would look.  Here, we also spe
 
 
 Output file format
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 By default ``homonim`` writes output files as *GeoTIFF*\s with *DEFLATE* compression, *float32* data type and *nan* nodata value.  These options are all configurable.
 
-Here we create a corrected image in *JPEG* format, with *uint8* data type, *0* nodata value, and a *QUALITY* setting of *85*.
+Here we create a *JPEG* compressed image in *GeoTIFF* format, with *uint8* data type:
 
 .. code:: shell
 
-    homonim fuse -od ./corrected  --driver JPEG --dtype uint8 --nodata 0 -co QUALITY=85 ./source/ngi_rgb_byte_4.tif ./reference/sentinel2_b432_byte.tif
+    homonim fuse -od ./corrected --driver GTiff --dtype uint8 --nodata null -co COMPRESS=JPEG -co INTERLEAVE=PIXEL -co PHOTOMETRIC=YCBCR ./source/ngi_rgb_byte_4.tif ./reference/sentinel2_b432_byte.tif
 
+Setting nodata to *null* forces the writing of an internal mask.  This avoids lossy compression `transparency artifacts <https://gis.stackexchange.com/questions/114370/compression-artifacts-and-gdal>`__.  JPEG compression is configured to sub-sample YCbCr colour space values with the ``-co INTERLEAVE=PIXEL -co PHOTOMETRIC=YCBCR`` creation options.
+
+Next, the corrected image is formatted as a 12 bit JPEG compressed GeoTIFF.  A *null* nodata value is used again to write an internal mask, and the *uint16* data type gets truncated to 12 bits:
+
+.. code:: shell
+
+    homonim fuse -od ./corrected --driver GTiff --dtype uint16 --nodata null -co COMPRESS=JPEG -co NBITS=12 ./source/ngi_rgb_byte_4.tif ./reference/sentinel2_b432_byte.tif
+
+The ``-co INTERLEAVE=PIXEL -co PHOTOMETRIC=YCBCR`` creation options could also be used with this example, to further compress the RGB image.
+
+.. note::
+
+    Support for 12 bit JPEG compression is `rasterio <https://rasterio.readthedocs.io/en/stable>`__ build / package dependent.
+
+See the `GDAL docs <https://gdal.org/drivers/raster/index.html>`__ for available drivers and their parameters.
 
 Usage
-^^^^^
+-----
 
 .. click:: homonim.cli:cli
   :prog: homonim

docs/contributing.rst

@@ -0,0 +1,8 @@
+Contributing
+============
+
+Bug reports and feature requests are welcome, and can be made with the `github issue tracker <https://github.com/leftfield-geospatial/homonim/issues>`__.
+
+If ``homonim`` is useful to you, please consider `making a donation <https://github.com/sponsors/leftfield-geospatial>`__ to fund its development.
+
+While a lack of funding shouldn't prevent you from making feature requests, funded requests will be prioritised.

docs/index.rst

@@ -26,6 +26,7 @@ Contents
    api
    advanced
    tutorials
+   contributing
 
 * :ref:`genindex`
 

homonim/__init__.py

@@ -18,13 +18,24 @@
 """
 import os
 import pathlib
+import logging
+import warnings
 
+from rasterio.errors import NotGeoreferencedWarning
 from homonim.compare import RasterCompare
 from homonim.enums import Model, ProcCrs
 from homonim.fuse import RasterFuse
 from homonim.kernel_model import KernelModel
 from homonim.stats import ParamStats
 
+# suppress NotGeoreferencedWarning which rasterio can raise incorrectly
+warnings.simplefilter('ignore', category=NotGeoreferencedWarning)
+
+# Add a NullHandler to the package logger to hide logs by default.  Applications can then add
+# their own handler(s).
+log = logging.getLogger(__name__)
+log.addHandler(logging.NullHandler())
+
 if '__file__' in globals():
     root_path = pathlib.Path(__file__).absolute().parents[1]
 else: