A fast resampling software with simple to plugin library.

Overview • Docker App • How To Build • How To Use • Acknowledgement

As of today, and to our knowledge, there is no complete open source resampling tool for satellite imagery based on frequency resampling. Numerous softwares, some being open source, can be found to resample (most of the time upsample) data. Most of them offers various interpolators (GIMP, Pandore, Getreuer, OTB), some being very fast but rather innacurate (nearest neighbors, bilinear) and some offering high quality results (more often than not based on a Lancsoz convolutional kernel) but being very time consuming. Then only a few provides ways to deal efficiently with large amount of data (OTB) or proposes a fast and accurate sinus cardinal interpolator implemented as frequencial zero padding (Getreuer). None of those however allows one to resample satellite images in frequency domain with a floating upscaling or downscaling factor.

It could be argued that the OTB remains the best solution for the purpose of resampling satellite images. However, and though there exists ways to filter satellite images in frequency domain with the OTB, it is not possible to resample such an image in frequency domain.

Sirius then aims at filling this void offering a fast and simple to plug-in resampling C++ library that is taking advantage of the Fourier Transform.

Overview

• Theoretical Basis Documentation
• Internals

Docker App

Sirius is delivered inside a docker container. Assuming one has previously installed docker, then Sirius can be launched using the following commands :

# pull image from the registry
docker pull ldumas/sirius_dockerfile:sirius
# then run sirius
docker run ldumas/sirius_dockerfile:sirius [OPTION...] input-image output-image

# if no arguments are set then sirius is launched without any argument and its help is displayed
# see below for the list of sirius args

# note that using docker volume might be a good solution to give the container access to input-image
# and to give host access to the output-image :
docker run -v /home/user/outdir/:/outdir -v /home/user/input_images:/input ldumas/sirius_dockerfile:sirius /input/input-image.tif /outdir/output-image.tif -z 1 -d 2

How to Build

Sirius is using CMake to build its libraries and executables.

Requirements

• C++14 compiler (GCC >= 5)
• CMake >=3.2
• GDAL development kit, >=2
• FFTW development kit, >=3
• Doxygen if documentation option is enabled

Internal dependencies

• spdlog v0.17.0
• cxxopts v2.1.0
• GSL v1.0.0
• catch v2.2.3
• cmake-modules

Options

• CMAKE_BUILD_TYPE: Debug, Release, RelWithDebInfo or MinSizeRel
• CMAKE_INSTALL_PREFIX: directory path where the built artifacts (include directory, library, docs) will be gathered
• ENABLE_CACHE_OPTIMIZATION: set to ON to build with cache optimization for FFTW and Filter
• ENABLE_GSL_CONTRACTS: set to ON to build with GSL contracts (e.g. bounds checking). This option should be OFF on release mode.
• ENABLE_LOGS: set to ON if you want to build Sirius with the logs
• ENABLE_UNIT_TESTS: set to ON if you want to build the unit tests
• ENABLE_DOCUMENTATION: set to ON if you want to build the documentation

Example

# CWD is Sirius root directory
mkdir .build
cd .build
cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_INSTALL_PREFIX=/tmp/sirius \
         -DENABLE_CACHE_OPTIMIZATION=ON \
         -DENABLE_GSL_CONTRACTS=OFF \
         -DENABLE_LOGS=ON \
         -DENABLE_UNIT_TESTS=OFF \
         -DENABLE_DOCUMENTATION=ON
cmake --build . --target sirius
cmake --build . --target doc
cmake --build . --target install

How to use

Host requirements

• GDAL library
• FFTW3 library

Sirius standalone tool

Sirius is shipped as a standalone tool that offers filtering and zoom in/out features.

./sirius -h
Sirius X.Y.Z (...)
Standalone tool to resample images in the frequency domain

Usage:
  ./sirius [OPTION...] input-image output-image

  -h, --help           Show help
  -v, --verbosity arg  Set verbosity level
                       (trace,debug,info,warn,err,critical,off) (default: info)

 zoom options:
  -z, --input-resolution arg   Numerator of the zoom ratio (default: 1)
  -d, --output-resolution arg  Denominator of the zoom ratio (default: 1)
      --id-periodic-smooth     Use Periodic plus Smooth image decomposition
                               (default is regular image decomposition)
      --zoom-zero-padding      Use zero padding zoom algorithm (default is
                               periodization zoom algorithm)

 filter options:
      --filter arg           Path to the filter image to apply to the zoomed
                             image
      --filter-no-padding    Do not add filter margins on input borders
                             (default is mirror padding)
      --filter-zero-padding  Use zero padding strategy to add filter margins
                             on input borders (default is mirror padding)
      --filter-normalize     Normalize filter coefficients (default is no
                             normalization)

 streaming options:
      --stream                  Enable stream mode
      --block-width arg         Width of a stream block (default: 256)
      --block-height arg        Height of a stream block (default: 256)
      --no-block-resizing       Disable block resizing optimization
      --parallel-workers [=arg(=1)]
                                Parallel workers used to compute zoom (8 max)
                                (default: 1)

Processing mode options

Regular mode

Regular mode (default mode) will put the whole image in memory and then processed it. This mode should only be used on small image.

This command line will zoom in the image /path/to/input-file.tif by 4/3 with the periodic plus smooth image decomposition, apply the filter /path/to/filter-image.tif to the zoomed image and write the result into /path/to/output-file.tif.

./sirius -z 4 -d 3 \
         --id-periodic-smooth \
         --filter /path/to/filter-image.tif \
         /path/to/input-file.tif /path/to/output-file.tif

Stream mode

Stream mode is activated with the option --stream. It will cut the image into multiple blocks of small size (default block size is 256x256). Each block will be processed separately and result blocks will be aggregated to generate the output image. This mode must be used on large image.

Stream mode can be run in mono-threaded context (--parallel-workers=1) or in multi-threaded context (--parallel-workers=N where N is the requested number of threads which will compute the zoom).

./sirius -z 4 -d 3 \
         --stream --parallel-workers=4 \
         --id-periodic-smooth \
         --filter /path/to/filter-image.tif \
         /path/to/input-file.tif /path/to/output-file.tif

It is possible to customize block size with the options --block-witdh=XXX and --block-height=YYY.

Default behavior tries to optimize block size so that the processed block (block size + filter margins) width and height are dyadic. You can disable this optimization with the option --no-block-resizing.

When dealing with real zoom, block width and height are computed so that they comply with the zoom ratio.

Zoom options

Sirius can use two image decomposition algorithms:

• Regular (default behavior) is using raw image data without any processing.
• Periodic plus Smooth (--id-periodic-smooth) is splitting the input image into a periodic part and a smooth image part.

Sirius can use two zoom strategies:

• Periodization (default behavior)
• Zero padding (--zoom-zero-padding)

More details on algorithms in the Theoretical Basis documentation.

Filter options

A filter image path can be specified with the option --filter. This filter will be applied:

• on the zoomed image if the image is zoomed in
• on the source image if the image is zoomed out

Default behavior will pad filter margins with a mirroring of the image borders.

--filter-no-padding will change the padding strategy and will not pad filter margins on the image borders.

--filter-zero-padding will change the padding strategy and zero pad filter margins on the image borders.

It is assumed that the filter is already normalized. If not, the option --filter-normalize will normize it before any processing.

More details on filters in the Theoretical Basis documentation.

Examples

Zoom in

The following command line will zoom in input/lena.jpg by 2 using periodic plus smooth image decomposition and zero padding zoom.

./sirius -z 2 -d 1 \
         --id-periodic-smooth --zoom-zero-padding \
         input/lena.jpg output/lena_z2.jpg

The following command line will zoom in input/lena.jpg by 2 using periodic plus smooth image decomposition, periodization zoom and filter for zoom 2.

./sirius -z 2 -d 1 \
         --id-periodic-smooth \
         input/lena.jpg output/lena_z2.jpg

The following command line will zoom in input/sentinel2_20m.tif by 2 using stream mode and 8 workers, periodic plus smooth image decomposition, periodization zoom and filter for zoom 2.

./sirius --stream --parallel-workers=8 \
         -z 2 -d 1 \
         --id-periodic-smooth \
         --filter filters/ZOOM_2.tif \
         input/sentinel2_20m.tif output/sentinel2_20m_z2.tif

Zoom out

The following command line will zoom out input/lena.jpg by 1/2 using periodic plus smooth image decomposition and filter for zoom 1/2.

./sirius -z 1 -d 2 \
         --id-periodic-smooth --zoom-zero-padding \
         --filter filters/ZOOM_1_2.tif \
         input/lena.jpg output/lena_z2.jpg

The following command line will zoom out input/disparity.png by 1/2 using periodic plus smooth image decomposition and filter for zoom 1/2.

./sirius -z 1 -d 2 \
         --id-periodic-smooth \
         --filter filters/ZOOM_1_2.tif \
         input/disparity.png output/disparity_z1_2.jpg

The following command line will zoom out input/sentinel2_10m.tif by 1/2 using using stream mode and 8 workers, periodic plus smooth image decomposition and filter for zoom 1/2.

./sirius --stream --parallel-workers=8 \
         -z 1 -d 2 \
         --id-periodic-smooth \
         --filter filters/ZOOM_1_2.tif \
         input/sentinel2_10m.tif output/sentinel2_10m_z1_2.tif

Sirius library API

Sirius is designed to be easy to use.

The main interface to compute a frequency zoom is IFrequencyZoom and it only requires an image, a zoom ratio and an optional filter.

IFrequencyZoom objects are instantiated by the FrequencyZoomFactory.

Example without filter

#include "sirius/filter.h"
#include "sirius/frequency_zoom_factory.h"
#include "sirius/image.h"
#include "sirius/types.h"

// create an image
sirius::Image image = {...};

// configure the zoom ratio
sirius::ZoomRatio zoom_ratio{7, 5};

// compose a frequency zoom from sirius::ImageDecompositionPolicies and
//     sirius::FrequencyZoomStrategies enums
sirius::IFrequencyZoom::UPtr freq_zoom =
      sirius::FrequencyZoomFactory::Create(
            sirius::ImageDecompositionPolicies::kRegular,
            sirius::FrequencyZoomStrategies::kZeroPadding);

// compute the zoomed image
sirius::Image zoomed_image = freq_zoom->Compute(
      zoom_ratio, image, {}, {});

Example with filter

#include "sirius/filter.h"
#include "sirius/frequency_zoom_factory.h"
#include "sirius/image.h"
#include "sirius/types.h"

// create an image
sirius::Image image = {...};

// configure the zoom ratio
sirius::ZoomRatio zoom_ratio = {7, 5};

// create a filter from an image file
sirius::Filter filter = sirius::Filter::Create("/path/to/filter/file.tif",
                                               zoom_ratio);

// compose a frequency zoom from sirius::ImageDecompositionPolicies and
//     sirius::FrequencyZoomStrategies enums
sirius::IFrequencyZoom::UPtr freq_zoom =
      sirius::FrequencyZoomFactory::Create(
            sirius::ImageDecompositionPolicies::kPeriodicSmooth,
            sirius::FrequencyZoomStrategies::kZeroPadding);

// compute the zoomed image
sirius::Image zoomed_image = freq_zoom->Compute(
      zoom_ratio, image, filter.padding(), filter);

Thread safety

Compute a zoomed image with Sirius is thread safe so it is possible to use the same IFrequencyZoom object in a multi-threaded context.

Process an image with a Filter object is also thread safe so you can reuse the same filter in a multi-threaded context.

Unit tests

Running tests requires data features (input image, filters) which are available here.

You need to execute the tests in the root directory of those data features. Expected directory tree is:

ROOT_DATA_FEATURES/input
                  /filters
                  /output

frequency_zoom_tests and functional_tests will create output images in the directory ROOT_DATA_FEATURES/output

Acknowledgement

Sirius developers would like to thank:

• Matteo Frigo, Steven G. Johnson et al. for FFTW3 library (GNU General Public License v3)
• GDAL (MIT License) project team
• Gabi Melman et al. for spdlog (MIT License)
• Jarryd Beck et al. for cxxopts (MIT License)
• Catch2 (Boost Software License - Version 1.0) project team
• GSL (MIT License) project team
• Ryan Pavlik et al. for cmake-modules (Boost Software License - Version 1.0)