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.
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 -r 1:2
Sirius is using CMake to build its libraries and executables.
CMAKE_BUILD_TYPE
: Debug, Release, RelWithDebInfo or MinSizeRelCMAKE_INSTALL_PREFIX
: directory path where the built artifacts (include directory, library, docs) will be gathered using install targetSIRIUS_VERSION
: set Sirius library version (default is 0.0.0
)SIRIUS_REVISION_COMMIT
: set Sirius library revision commit (default is sirius-no-revision-commit
)ENABLE_SIRIUS_EXECUTABLE
: set to ON
to enable sirius target executableENABLE_CACHE_OPTIMIZATION
: set to ON
to build with cache optimization for FFTW and FilterENABLE_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 logsENABLE_UNIT_TESTS
: set to ON
if you want to build the unit testsENABLE_DOCUMENTATION
: set to ON
if you want to build the documentationSirius version can be extracted from git describe
and revision commit from git rev-parse HEAD
.
If version and revision commit are not provided, CMake will try to extract them with the latter git commands.
# CWD is Sirius root directory
mkdir .build
cd .build
cmake .. -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/tmp/sirius \
-DENABLE_SIRIUS_EXECUTABLE=ON \
-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
See also .travis.yml
and .travis/create_cmake_project.sh
Sirius is shipped as a standalone tool that offers filtering and resampling features.
$ ./sirius -h
Sirius X.Y.Z (...)
Standalone tool to resample and filter 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)
resampling options:
-r, --resampling-ratio arg Resampling ratio as input:output, allowed
format: I (equivalent to I:1), I:O (default: 1:1)
--no-image-decomposition Do not decompose the input image (default:
periodic plus smooth image decomposition)
--upsample-periodization Force periodization as upsampling algorithm
(default algorithm if a filter is provided). A
filter is required to use this algorithm
--upsample-zero-padding Force zero padding as upsampling algorithm
(default algorithm if no filter is provided)
filter options:
--filter arg Path to the filter image to apply to the source
or resampled image
--filter-normalize Normalize filter coefficients (default is no
normalization)
--zero-pad-real-edges Force zero padding strategy on real input edges
(default: mirror padding)
--hot-point-x arg Hot point x coordinate (considered centered if
no value is provided)
--hot-point-y arg Hot point y coordinate (considered centered if
no value is provided)
streaming options:
--stream Enable stream mode
--block-width arg Initial width of a stream block (default:
256)
--block-height arg Initial height of a stream block (default:
256)
--no-block-resizing Disable block resizing optimization
--parallel-workers [=arg(=1)]
Parallel workers used to compute resampling
(8 max) (default: 1)
Regular mode (default mode) will put the whole image in memory and then processed it. This mode should only be used on small image.
The following 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-4-3.tif
to the zoomed image and write the result into /path/to/output-file.tif
.
./sirius -r 4:3 \
--filter /path/to/filter-image-4-3.tif \
/path/to/input-file.tif /path/to/output-file.tif
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 resampling).
./sirius -r 4:3 \
--stream --parallel-workers=4 \
--filter /path/to/filter-image-4-3.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 given 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.
Resampling ratio is specified with the option -r
. Expected format ratios are:
-r INPUT_RESOLUTION
where INPUT_RESOLUTION is a positive integer (e.g. -r 2
).-r INPUT_RESOLUTION:OUTPUT_RESOLUTION
where INPUT_RESOLUTION and OUTPUT_RESOLUTION are positive integers (e.g. -r 2:1
).Sirius can use two image decomposition algorithms:
--no-image-decomposition
) is using raw image data without any processing.Sirius can use two upsampling strategies:
Upsampling strategies can be forced with the following options:
--upsampling-zero-padding
--upsampling-periodization
Force periodization upsampling without providing a filter will result in an error.
More details on algorithms in the Theoretical Basis documentation.
A filter image path can be specified with the option --filter
. This filter will be applied:
Default behavior will pad real input edges with a mirroring of the edges.
--zero-pad-real-edges
will change this strategy and zero pad real input edges.
It is assumed that the filter is already normalized. If not, the option --filter-normalize
will normize it before any processing.
Finally, it is possible to give a filter which has an uncentered hot point by specifying its coordinates thanks to --hot-point-x
and --hot-point-y
options. In this case sirius will center the filter's hot point before any processing.
More details on filters in the Theoretical Basis documentation.
The following command line will zoom in input/lena.jpg
by 2 using periodic plus smooth image decomposition and zero padding upsampling.
./sirius -r 2:1 \
--upsample-zero-padding \
data/input/lena.jpg /tmp/lena_z2.jpg
The following command line will zoom in input/lena.jpg
by 2 using periodic plus smooth image decomposition, periodization upsampling and filter for upsampling 2.
./sirius -r 2 \
--filter data/filters/ZOOM_2.tif \
data/input/lena.jpg /tmp/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 upsampling and filter for upsampling 2.
./sirius --stream --parallel-workers=8 \
-r 2 \
--filter data/filters/ZOOM_2.tif \
data/input/sentinel2_20m.tif /tmp/sentinel2_20m_z2.tif
The following command line will zoom out input/lena.jpg
by 1/2 using periodic plus smooth image decomposition and filter for downsampling 1/2.
./sirius -r 1:2 \
--filter data/filters/ZOOM_1_2.tif \
data/input/lena.jpg /tmp/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 downsampling 1/2.
./sirius -r 1:2 \
--filter data/filters/ZOOM_1_2.tif \
data/input/disparity.png /tmp/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 downsampling 1/2.
./sirius --stream --parallel-workers=8 \
-r 1:2 \
--filter data/filters/ZOOM_1_2.tif \
data/input/sentinel2_10m.tif /tmp/sentinel2_10m_z1_2.tif
Sirius is designed to be easy to use.
The main interface to compute a frequency resampling is IFrequencyResampler
and it only requires an image, a zoom ratio and an optional filter.
IFrequencyResampler
objects are instantiated by the FrequencyResamplerFactory
.
#include "sirius/filter.h"
#include "sirius/frequency_resampler_factory.h"
#include "sirius/image.h"
#include "sirius/types.h"
// create an image
sirius::Image image = {...};
// configure the zoom ratio
sirius::ZoomRatio zoom_ratio = sirius::ZoomRatio::Create(7, 5);
// compose a frequency resampler from sirius::ImageDecompositionPolicies and
// sirius::FrequencyZoomStrategies enums
sirius::IFrequencyResampler::UPtr freq_resampler =
sirius::FrequencyResamplerFactory::Create(
sirius::ImageDecompositionPolicies::kPeriodicSmooth,
sirius::FrequencyZoomStrategies::kZeroPadding);
// compute the resampled image
sirius::Image resampled_image = freq_resampler->Compute(
zoom_ratio, image, {}, {});
#include "sirius/filter.h"
#include "sirius/frequency_resampler_factory.h"
#include "sirius/image.h"
#include "sirius/types.h"
// load an image
sirius::Image image = {...};
// load a filter image
sirius::Image filter_image = {...};
// configure the zoom ratio
sirius::ZoomRatio zoom_ratio = sirius::ZoomRatio::Create(7, 5);
// create a filter from an image file
sirius::Filter filter = sirius::Filter::Create(filter_image, zoom_ratio);
// compose a frequency resampler from sirius::ImageDecompositionPolicies and
// sirius::FrequencyZoomStrategies enums
sirius::IFrequencyResampler::UPtr freq_resampler =
sirius::FrequencyResamplerFactory::Create(
sirius::ImageDecompositionPolicies::kPeriodicSmooth,
sirius::FrequencyZoomStrategies::kPeriodization);
// compute the resampled image
sirius::Image resampled_image = freq_resampler->Compute(
zoom_ratio, image, filter.padding(), filter);
Compute a resampled image with Sirius is thread safe so it is possible to use the same IFrequencyResampler
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.
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_resampler_tests
and functional_tests
will create output images in the directory ROOT_DATA_FEATURES/output
Sirius developers would like to thank: