Yalantis/uCrop · error · CImgArgumentException

CImgList<%s>::FFT(): Invalid specified axis '%c' for real an

Error message

CImgList<%s>::FFT(): Invalid specified axis '%c' for real and imaginary parts (%u,%u,%u,%u) (should be { x | y | z }).

What it means

CImgList<T>::FFT() validates its axis argument by lowercasing it and requiring it to be 'x', 'y' or 'z'. Any other character is rejected because FFT can only be computed along one of the three image dimensions. This is an argument-validation guard in ucrop/src/main/jni/CImg.h before any FFT work starts.

Source

Thrown at ucrop/src/main/jni/CImg.h:47667

       \param[in,out] imag Imaginary part of the pixel values.
       \param axis Axis along which the FFT is computed.
       \param is_inverse Tells if the forward (\c false) or inverse (\c true) FFT is computed.
    **/
    static void FFT(CImg<T>& real, CImg<T>& imag, const char axis, const bool is_inverse=false,
                    const unsigned int nb_threads=0) {
      if (!real)
        throw CImgInstanceException("CImg<%s>::FFT(): Specified real part is empty.",
                                    pixel_type());
      if (!imag) imag.assign(real._width,real._height,real._depth,real._spectrum,(T)0);
      if (!real.is_sameXYZC(imag))
        throw CImgInstanceException("CImg<%s>::FFT(): Specified real part (%u,%u,%u,%u,%p) and "
                                    "imaginary part (%u,%u,%u,%u,%p) have different dimensions.",
                                    pixel_type(),
                                    real._width,real._height,real._depth,real._spectrum,real._data,
                                    imag._width,imag._height,imag._depth,imag._spectrum,imag._data);
      const char _axis = cimg::lowercase(axis);
      if (_axis!='x' && _axis!='y' && _axis!='z')
        throw CImgArgumentException("CImgList<%s>::FFT(): Invalid specified axis '%c' for real and imaginary parts "
                                    "(%u,%u,%u,%u) "
                                    "(should be { x | y | z }).",
                                    pixel_type(),axis,
                                    real._width,real._height,real._depth,real._spectrum);
      cimg::unused(nb_threads);
#ifdef cimg_use_fftw3
      cimg::mutex(12);
#ifndef cimg_use_fftw3_singlethread
      fftw_plan_with_nthreads(nb_threads?nb_threads:cimg::nb_cpus());
#endif
      fftw_complex *data_in = (fftw_complex*)fftw_malloc(sizeof(fftw_complex)*real._width*real._height*real._depth);
      if (!data_in)
        throw CImgInstanceException("CImgList<%s>::FFT(): Failed to allocate memory (%s) "
                                    "for computing FFT of image (%u,%u,%u,%u) along the X-axis.",
                                    pixel_type(),
                                    cimg::strbuffersize(sizeof(fftw_complex)*real._width*real._height*real._depth),
                                    real._width,real._height,real._depth,real._spectrum);
      double *const ptrf = (double*)data_in;

View on GitHub (pinned to f788b534b4)

Solutions

  1. Pass one of the literal characters 'x', 'y' or 'z' (case does not matter; it is lowercased internally).
  2. Validate/normalize the axis string before the call, rejecting anything not in {x,y,z}.
  3. If you have a numeric axis, map it: 0->'x', 1->'y', 2->'z'.

Example fix

// before
img.FFT(true, false, 'X');  // or FFT(..., 'w')
// after
img.FFT(true, false, 'x');  // only 'x', 'y' or 'z' allowed
Defensive patterns

Strategy: validation

Validate before calling

char a = std::tolower(axis);
if (a != 'x' && a != 'y' && a != 'z') throw std::invalid_argument("axis must be x, y or z");

Type guard

bool isValidAxis(char c) { return c=='x'||c=='X'||c=='y'||c=='Y'||c=='z'||c=='Z'; }

Try / catch

try { img.FFT(is_inverse, /*axis*/'x'); }
catch (CImgArgumentException& e) { std::cerr << "Bad FFT axis: " << e.what() << std::endl; }

Prevention

When it happens

Trigger: Calling CImgList<T>::FFT() or the static CImg<T>::FFT(real, imag, is_inverse, nb_threads) variant with an axis character other than 'x', 'y', or 'z' (case-insensitive), e.g. axis='w', a typo like 'X ' with trailing whitespace, or a variable holding an uninitialized char.

Common situations: Typo in the axis literal, passing a user-supplied axis string without validating it, porting code that used a numeric axis index (0/1/2) where CImg expects a character, or reading the axis from config where an empty/invalid value slips through.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of Yalantis/uCrop@f788b534b4 (2026-09-08). Data as JSON: /api/errors/7e9c9d87472eaf30. Report an issue: GitHub.