<commit_before>/*
 * DIPlib 3.0
 * This file contains declarations for geometric transformations
 *
 * (c)2017-2018, <NAME>.
 * Based on original DIPlib code: (c)1995-2014, Delft University of Technology.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
*/

#ifndef DIP_GEOMETRY_H
#define DIP_GEOMETRY_H

#include "diplib.h"
#include "diplib/boundary.h"


/// \file
/// \brief Functions for geometric image transformations
/// \see geometry


namespace dip {


/// \defgroup geometry Geometric transformations
/// \brief Geometric image transformations.
///
/// \section interpolation_methods Interpolation methods
///
/// Many of the functions in this group resample the image using an interpolation method. They all perform
/// interpolation separately (i.e. along one dimension at the time). These functions have an input argument
/// called `interpolationMethod`, which determines how image data is interpolated. It can be set to one of
/// the following strings:
///
///  - `"3-cubic"` (or `""`): Third-order cubic spline interpolation (Keys, 1981), using 4 input samples to
///    compute each output sample. This is the default method for most functions.
///
///  - `"4-cubic"`: Fourth-order cubic spline interpolation (Keys, 1981), using 6 input samples to compute
///    compute each output sample.
///
///  - `"linear"`: Linear interpolation, using 2 input samples to compute each output sample.
///
///  - `"nearest"` (or `"nn"`): Nearest neighbor interpolation, samples are simply shifted and replicated.
///
///  - `"inverse nearest"` (or `"nn2"`): Nearest neighbor interpolation, but resolves the rounding of x.5 in
///    the opposite direction that `"nearest"` does. This is useful when applying the inverse of an earlier
///    transform, to be able to obtain the original geometry back.
///
///  - `"bspline"`: A third-order cardinal B-spline is computed for all samples on an image line, which is
///    sampled anew to obtain the interpolated sample values. All input samples are used to compute all
///    output samples, but only about 10 input samples significantly influence each output value.
///
///  - `"lanczos8"`: Lanczos interpolation with *a* = 8, using 16 input samples to compute each output sample.
///    The Lanczos kernel is a sinc function windowed by a larger sinc function, where *a* is the width of
///    the larger sinc function. The kernel is normalized.
///
///  - `"lanczos6"`: Lanczos interpolation with *a* = 6, using 12 input samples to compute each output sample.
///
///  - `"lanczos4"`: Lanczos interpolation with *a* = 4, using 8 input samples to compute each output sample.
///
///  - `"lanczos3"`: Lanczos interpolation with *a* = 3, using 6 input samples to compute each output sample.
///
///  - `"lanczos2"`: Lanczos interpolation with *a* = 2, using 4 input samples to compute each output sample.
///
///  - `"ft"`: Interpolation through padding and cropping, and/or modifying the phase component of the
///    Fourier transform of the image line. Padding with zeros increases the sampling density, cropping
///    reduces the sampling density, and multiplying the phase component by \f$-j s \omega\f$ shifts
///    the image. Equivalent to interpolation with a sinc kernel. All input samples are used to compute
///    all output samples. The boundary condition is ignored, as the Fourier transform imposes a periodic
///    boundary condition.
///
/// Not all methods are available for all functions. If so, this is described in the function's documentation.
/// For operations on binary images, the interpolation method is ignored, and `"nearest"` is always used.
///
/// Interpolation methods require a boundary extension of half the number of input samples used to compute
/// each output sample. For B-spline interpolation, a boundary extension of 5 is used. For the nearest neighbor
/// and Fourier interpolation methods, no boundary extension is needed.
///
/// **Literature**
/// - <NAME>, "Cubic Convolution Interpolation for Digital Image Processing", IEEE Transactions on
///   Acoustics, Speech, and Signal Processing 29(6):1153-1160, 1981.
/// \{

/// \brief Shifts the input image by an integer number of pixels, wrapping the pixels around.
///
/// `%dip::Wrap` is equivalent to `dip::Shift` with nearest neighbor interpolation and periodic
/// boundary condition, but faster.
DIP_EXPORT void Wrap(
      Image const& in,
      Image& out,
      IntegerArray wrap
);
inline Image Wrap(
      Image const& in,
      IntegerArray const& wrap
) {
   Image out;
   Wrap( in, out, wrap );
   return out;
}


/// \brief Subsamples the input image.
///
/// The input image is subsampled by `sample[ ii ]` along dimension `ii`. The output image shares
/// the data segment of the input image, meaning that no data is copied. If a data copy is required,
/// calling `dip::Image::ForceContiguousData` after subsampling should trigger a data copy.
inline void Subsampling(
      Image const& in,
      Image& out,
      UnsignedArray const& sample
) {
   Image tmp; // will be a window onto `in`.
   DefineROI( in, tmp, {}, {}, sample );
   out.Copy( tmp );
}
inline Image Subsampling(
      Image const& in,
      UnsignedArray const& sample
) {
   Image out;
   Subsampling( in, out, sample );
   return out;
}


/// \brief Resamples an image with the given zoom factor and sub-pixel shift.
///
/// The shift is applied first, and causes part of the image to shift out of the field of view.<commit_msg>A small improvement to `dip::Subsampling`.<commit_after>/*
 * DIPlib 3.0
 * This file contains declarations for geometric transformations
 *
 * (c)2017-2018, <NAME>.
 * Based on original DIPlib code: (c)1995-2014, Delft University of Technology.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
*/

#ifndef DIP_GEOMETRY_H
#define DIP_GEOMETRY_H

#include "diplib.h"
#include "diplib/boundary.h"


/// \file
/// \brief Functions for geometric image transformations
/// \see geometry


namespace dip {


/// \defgroup geometry Geometric transformations
/// \brief Geometric image transformations.
///
/// \section interpolation_methods Interpolation methods
///
/// Many of the functions in this group resample the image using an interpolation method. They all perform
/// interpolation separately (i.e. along one dimension at the time). These functions have an input argument
/// called `interpolationMethod`, which determines how image data is interpolated. It can be set to one of
/// the following strings:
///
///  - `"3-cubic"` (or `""`): Third-order cubic spline interpolation (Keys, 1981), using 4 input samples to
///    compute each output sample. This is the default method for most functions.
///
///  - `"4-cubic"`: Fourth-order cubic spline interpolation (Keys, 1981), using 6 input samples to compute
///    compute each output sample.
///
///  - `"linear"`: Linear interpolation, using 2 input samples to compute each output sample.
///
///  - `"nearest"` (or `"nn"`): Nearest neighbor interpolation, samples are simply shifted and replicated.
///
///  - `"inverse nearest"` (or `"nn2"`): Nearest neighbor interpolation, but resolves the rounding of x.5 in
///    the opposite direction that `"nearest"` does. This is useful when applying the inverse of an earlier
///    transform, to be able to obtain the original geometry back.
///
///  - `"bspline"`: A third-order cardinal B-spline is computed for all samples on an image line, which is
///    sampled anew to obtain the interpolated sample values. All input samples are used to compute all
///    output samples, but only about 10 input samples significantly influence each output value.
///
///  - `"lanczos8"`: Lanczos interpolation with *a* = 8, using 16 input samples to compute each output sample.
///    The Lanczos kernel is a sinc function windowed by a larger sinc function, where *a* is the width of
///    the larger sinc function. The kernel is normalized.
///
///  - `"lanczos6"`: Lanczos interpolation with *a* = 6, using 12 input samples to compute each output sample.
///
///  - `"lanczos4"`: Lanczos interpolation with *a* = 4, using 8 input samples to compute each output sample.
///
///  - `"lanczos3"`: Lanczos interpolation with *a* = 3, using 6 input samples to compute each output sample.
///
///  - `"lanczos2"`: Lanczos interpolation with *a* = 2, using 4 input samples to compute each output sample.
///
///  - `"ft"`: Interpolation through padding and cropping, and/or modifying the phase component of the
///    Fourier transform of the image line. Padding with zeros increases the sampling density, cropping
///    reduces the sampling density, and multiplying the phase component by \f$-j s \omega\f$ shifts
///    the image. Equivalent to interpolation with a sinc kernel. All input samples are used to compute
///    all output samples. The boundary condition is ignored, as the Fourier transform imposes a periodic
///    boundary condition.
///
/// Not all methods are available for all functions. If so, this is described in the function's documentation.
/// For operations on binary images, the interpolation method is ignored, and `"nearest"` is always used.
///
/// Interpolation methods require a boundary extension of half the number of input samples used to compute
/// each output sample. For B-spline interpolation, a boundary extension of 5 is used. For the nearest neighbor
/// and Fourier interpolation methods, no boundary extension is needed.
///
/// **Literature**
/// - <NAME>, "Cubic Convolution Interpolation for Digital Image Processing", IEEE Transactions on
///   Acoustics, Speech, and Signal Processing 29(6):1153-1160, 1981.
/// \{

/// \brief Shifts the input image by an integer number of pixels, wrapping the pixels around.
///
/// `%dip::Wrap` is equivalent to `dip::Shift` with nearest neighbor interpolation and periodic
/// boundary condition, but faster.
DIP_EXPORT void Wrap(
      Image const& in,
      Image& out,
      IntegerArray wrap
);
inline Image Wrap(
      Image const& in,
      IntegerArray const& wrap
) {
   Image out;
   Wrap( in, out, wrap );
   return out;
}


/// \brief Subsamples the input image.
///
/// The input image is subsampled by `sample[ ii ]` along dimension `ii`. The output image shares
/// the data segment of the input image, meaning that no data is copied. If a data copy is required,
/// calling `dip::Image::ForceContiguousData` after subsampling should trigger a data copy.
///
/// If `out` has an external interface different from that of `in`, the data will be copied.
inline void Subsampling(
      Image const& in,
      Image& out,
      UnsignedArray const& sample
) {
   Image tmp; // will be a window onto `in`.
   DefineROI( in, tmp, {}, {}, sample );
   out = tmp;  // will copy if `out` has an external interface.
}
inline Image Subsampling(
      Image const& in,
      UnsignedArray const& sample
) {
   Image out;
   Subsampling( in, out, sample );
   return out;
}


/// \brief Resamples an image with the given zoom factor and sub-pixel shift.
///
/// The shift is applied first, and causes part of the image to shift out of the field of view.
{'fraction_non_alphanumeric': 0.1042904290429043, 'fraction_numerical': 0.011881188118811881, 'mean_word_length': 3.2425621281064054, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '630781', 'n_tokens_mistral': 3379, 'n_tokens_neox': 3154, 'n_words': 1587}