vpImage.h

/*
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2025 by Inria. All rights reserved.
 *
 * This software is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See the file LICENSE.txt at the root directory of this source
 * distribution for additional information about the GNU GPL.
 *
 * For using ViSP with software that can not be combined with the GNU
 * GPL, please contact Inria about acquiring a ViSP Professional
 * Edition License.
 *
 * See https://visp.inria.fr for more information.
 *
 * This software was developed at:
 * Inria Rennes - Bretagne Atlantique
 * Campus Universitaire de Beaulieu
 * 35042 Rennes Cedex
 * France
 *
 * If you have questions regarding the use of this file, please contact
 * Inria at visp@inria.fr
 *
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 *
 * Description:
 * Image handling.
 */

 
#ifndef VP_IMAGE_H
#define VP_IMAGE_H
 
#include <visp3/core/vpConfig.h>
#include <visp3/core/vpEndian.h>
#include <visp3/core/vpException.h>
#include <visp3/core/vpImageException.h>
#include <visp3/core/vpImagePoint.h>
#include <visp3/core/vpRGBa.h>
#include <visp3/core/vpRGBf.h>
 
#if defined(VISP_HAVE_THREADS)
#include <thread>
#endif
 
#include <fstream>
#include <iomanip> // std::setw
#include <iostream>
#include <math.h>
#include <string.h>
 
// Visual Studio 2010 or previous is missing inttypes.h
#if defined(_MSC_VER) && (_MSC_VER < 1700)
typedef long long int64_t;
typedef unsigned short uint16_t;
#else
#include <inttypes.h>
#endif
 
BEGIN_VISP_NAMESPACE
class vpDisplay;
// Ref: http://en.cppreference.com/w/cpp/language/friend#Template_friends
template <class Type> class vpImage; // forward declare to make function declaration possible
 
// declarations
template <class Type> std::ostream &operator<<(std::ostream &s, const vpImage<Type> &I);
 
std::ostream &operator<<(std::ostream &s, const vpImage<unsigned char> &I);
std::ostream &operator<<(std::ostream &s, const vpImage<char> &I);
std::ostream &operator<<(std::ostream &s, const vpImage<float> &I);
std::ostream &operator<<(std::ostream &s, const vpImage<double> &I);

template <class Type> class vpImage
{
  friend class vpImageConvert;
 
public:
  Type *bitmap; 
  vpDisplay *display;

  vpImage();
  vpImage(const vpImage<Type> &img);
#if ((__cplusplus >= 201103L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201103L))) // Check if cxx11 or higher
  vpImage(vpImage<Type> &&img);
#endif
  vpImage(unsigned int height, unsigned int width);
  vpImage(unsigned int height, unsigned int width, Type value);
  vpImage(Type *const array, unsigned int height, unsigned int width, bool copyData = false);
  virtual ~vpImage();

 
  // destructor
  void destroy();
 
  // Returns a new image that's double size of the current image
  void doubleSizeImage(vpImage<Type> &res);

  inline unsigned int getCols() const { return width; }

  inline unsigned int getHeight() const { return height; }
 
  // Return the maximum value within the bitmap
  Type getMaxValue(bool onlyFiniteVal = true) const;
  // Return the mean value of the bitmap
  double getMeanValue(const vpImage<bool> *p_mask = nullptr, unsigned int *nbValidPoints = nullptr) const;
 
  // Return the minumum value within the bitmap
  Type getMinValue(bool onlyFiniteVal = true) const;
  // Look for the minumum and the maximum value within the bitmap
  void getMinMaxValue(Type &min, Type &max, bool onlyFiniteVal = true) const;
  // Look for the minumum and the maximum value within the bitmap and get their location
  void getMinMaxLoc(vpImagePoint *minLoc, vpImagePoint *maxLoc, Type *minVal = nullptr, Type *maxVal = nullptr) const;

  inline unsigned int getNumberOfPixel() const { return npixels; }

  inline unsigned int getRows() const { return height; }

  inline unsigned int getSize() const { return width * height; }
 
  double getStdev(const vpImage<bool> *p_mask = nullptr, unsigned int *nbValidPoints = nullptr) const;
  double getStdev(const double &mean, const vpImage<bool> *p_mask = nullptr, unsigned int *nbValidPoints = nullptr) const;
 
  double getSum(const vpImage<bool> *p_mask = nullptr, unsigned int *nbValidPoints = nullptr) const;
 
  // Gets the value of a pixel at a location.
  Type getValue(unsigned int i, unsigned int j) const;
  // Gets the value of a pixel at a location with bilinear interpolation.
  Type getValue(double i, double j) const;
  // Gets the value of a pixel at a location with bilinear interpolation.
  Type getValue(const vpImagePoint &ip) const;

  inline unsigned int getWidth() const { return width; }
 
  // Returns a new image that's half size of the current image
  void halfSizeImage(vpImage<Type> &res) const;

  void init(unsigned int height, unsigned int width);
  void init(unsigned int height, unsigned int width, Type value);
  void init(Type *const array, unsigned int height, unsigned int width, bool copyData = false);
  void insert(const vpImage<Type> &src, const vpImagePoint &topLeft);
 
  //------------------------------------------------------------------
  // Access to the image

  inline Type *operator[](unsigned int i) { return row[i]; }
  inline Type *operator[](int i) { return row[i]; }

  inline const Type *operator[](unsigned int i) const { return row[i]; }
  inline const Type *operator[](int i) const { return row[i]; }

  inline Type operator()(unsigned int i, unsigned int j) const { return bitmap[(i * width) + j]; }

  inline void operator()(unsigned int i, unsigned int j, const Type &v) { bitmap[(i * width) + j] = v; }

  inline Type operator()(const vpImagePoint &ip) const
  {
    unsigned int i = static_cast<unsigned int>(ip.get_i());
    unsigned int j = static_cast<unsigned int>(ip.get_j());
 
    return bitmap[(i * width) + j];
  }

  inline void operator()(const vpImagePoint &ip, const Type &v)
  {
    unsigned int i = static_cast<unsigned int>(ip.get_i());
    unsigned int j = static_cast<unsigned int>(ip.get_j());
 
    bitmap[(i * width) + j] = v;
  }
 
  vpImage<Type> operator-(const vpImage<Type> &B) const;

  vpImage<Type> &operator=(const vpImage<Type> &other);
#if ((__cplusplus >= 201103L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201103L))) // Check if cxx11 or higher
  vpImage<Type> &operator=(vpImage<Type> &&other);
#endif
 
  vpImage<Type> &operator=(const Type &v);
  bool operator==(const vpImage<Type> &I) const;
  bool operator!=(const vpImage<Type> &I) const;
  friend std::ostream &operator<< <>(std::ostream &s, const vpImage<Type> &I);
  friend std::ostream &operator<<(std::ostream &s, const vpImage<unsigned char> &I);
  friend std::ostream &operator<<(std::ostream &s, const vpImage<char> &I);
  friend std::ostream &operator<<(std::ostream &s, const vpImage<float> &I);
  friend std::ostream &operator<<(std::ostream &s, const vpImage<double> &I);
 
  // Perform a look-up table transformation
  // static const unsigned int val_256 = 256;
  // void performLut(const Type(&lut)[val_256], unsigned int nbThreads = 1); // Doesn't pass CI
  void performLut(const Type(&lut)[256], unsigned int nbThreads = 1);
 
  // Returns a new image that's a quarter size of the current image
  void quarterSizeImage(vpImage<Type> &res) const;
 
  // set the size of the image without initializing it.
  void resize(unsigned int h, unsigned int w);
  // set the size of the image and initialize it.
  void resize(unsigned int h, unsigned int w, const Type &val);
 
  void sub(const vpImage<Type> &B, vpImage<Type> &C) const;
  void sub(const vpImage<Type> &A, const vpImage<Type> &B, vpImage<Type> &C) const;
  void subsample(unsigned int v_scale, unsigned int h_scale, vpImage<Type> &sampled) const;
 
  // See https://stackoverflow.com/questions/11562/how-to-overload-stdswap to understand why swap is in visp namespace
  friend void swap(vpImage<Type> &first, vpImage<Type> &second)
  {
    using std::swap;
    swap(first.bitmap, second.bitmap);
    swap(first.display, second.display);
    swap(first.npixels, second.npixels);
    swap(first.width, second.width);
    swap(first.height, second.height);
    swap(first.row, second.row);
  }

 
private:
  unsigned int npixels; 
  unsigned int width;   
  unsigned int height;  
  Type **row;           
  bool hasOwnership;    
};
 
#include <visp3/core/vpImage_operators.h>
#include <visp3/core/vpImage_lut.h>
#include <visp3/core/vpImage_getters.h>

template <class Type> void vpImage<Type>::init(unsigned int h, unsigned int w, Type value)
{
  init(h, w);
  std::fill(bitmap, bitmap + npixels, value);
}

template <class Type> void vpImage<Type>::init(unsigned int h, unsigned int w)
{
  if (h != this->height) {
    if (row != nullptr) {
      delete[] row;
      row = nullptr;
    }
  }
 
  if ((h != this->height) || (w != this->width)) {
    if (bitmap != nullptr) {
      if (hasOwnership) {
        delete[] bitmap;
      }
      bitmap = nullptr;
    }
  }
 
  this->width = w;
  this->height = h;
 
  npixels = width * height;
 
  if (bitmap == nullptr) {
    bitmap = new Type[npixels];
    hasOwnership = true;
  }
  if (bitmap == nullptr) {
    throw(vpException(vpException::memoryAllocationError, "cannot allocate bitmap "));
  }
  if (row == nullptr) {
    row = new Type *[height];
  }
  if (row == nullptr) {
    throw(vpException(vpException::memoryAllocationError, "cannot allocate row "));
  }
 
  for (unsigned int i = 0; i < height; ++i) {
    row[i] = bitmap + (i * width);
  }
}

template <class Type> void vpImage<Type>::init(Type *const array, unsigned int h, unsigned int w, bool copyData)
{
  if (h != this->height) {
    if (row != nullptr) {
      delete[] row;
      row = nullptr;
    }
  }
 
  // Delete bitmap if copyData==false, otherwise only if the dimension differs
  if ((copyData && ((h != this->height) || (w != this->width))) || (!copyData)) {
    if (bitmap != nullptr) {
      if (hasOwnership) {
        delete[] bitmap;
      }
      bitmap = nullptr;
    }
  }
 
  hasOwnership = copyData;
  this->width = w;
  this->height = h;
 
  npixels = width * height;
 
  if (copyData) {
    if (bitmap == nullptr) {
      bitmap = new Type[npixels];
    }
 
    if (bitmap == nullptr) {
      throw(vpException(vpException::memoryAllocationError, "cannot allocate bitmap "));
    }
 
    // Copy the image data
    memcpy(static_cast<void *>(bitmap), static_cast<void *>(array), static_cast<size_t>(npixels * sizeof(Type)));
  }
  else {
    // Copy the address of the array in the bitmap
    bitmap = array;
  }
 
  if (row == nullptr) {
    row = new Type *[height];
  }
  if (row == nullptr) {
    throw(vpException(vpException::memoryAllocationError, "cannot allocate row "));
  }
 
  for (unsigned int i = 0; i < height; ++i) {
    row[i] = bitmap + (i * width);
  }
}

template <class Type>
vpImage<Type>::vpImage(unsigned int h, unsigned int w)
  : bitmap(nullptr), display(nullptr), npixels(0), width(0), height(0), row(nullptr), hasOwnership(true)
{
  Type val(0);
  init(h, w, val);
}

template <class Type>
vpImage<Type>::vpImage(unsigned int h, unsigned int w, Type value)
  : bitmap(nullptr), display(nullptr), npixels(0), width(0), height(0), row(nullptr), hasOwnership(true)
{
  init(h, w, value);
}

template <class Type>
vpImage<Type>::vpImage(Type *const array, unsigned int h, unsigned int w, bool copyData)
  : bitmap(nullptr), display(nullptr), npixels(0), width(0), height(0), row(nullptr), hasOwnership(true)
{
  init(array, h, w, copyData);
}

template <class Type>
vpImage<Type>::vpImage() : bitmap(nullptr), display(nullptr), npixels(0), width(0), height(0), row(nullptr), hasOwnership(true)
{ }

template <class Type> void vpImage<Type>::resize(unsigned int h, unsigned int w) { init(h, w); }

template <class Type> void vpImage<Type>::resize(unsigned int h, unsigned int w, const Type &val) { init(h, w, val); }

template <class Type> void vpImage<Type>::destroy()
{
  if (bitmap != nullptr) {
    if (hasOwnership) {
      delete[] bitmap;
    }
    bitmap = nullptr;
  }
 
  if (row != nullptr) {
    delete[] row;
    row = nullptr;
  }
}

template <class Type> vpImage<Type>::~vpImage() { destroy(); }

template <class Type>
vpImage<Type>::vpImage(const vpImage<Type> &I)
  : bitmap(nullptr), display(nullptr), npixels(0), width(0), height(0), row(nullptr), hasOwnership(true)
{
  resize(I.getHeight(), I.getWidth());
  if (bitmap) {
    memcpy(static_cast<void *>(bitmap), static_cast<void *>(I.bitmap), I.npixels * sizeof(Type));
  }
}
 
#if ((__cplusplus >= 201103L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201103L))) // Check if cxx11 or higher
template <class Type>
vpImage<Type>::vpImage(vpImage<Type> &&I)
  : bitmap(I.bitmap), display(I.display), npixels(I.npixels), width(I.width), height(I.height), row(I.row),
  hasOwnership(I.hasOwnership)
{
  I.bitmap = nullptr;
  I.display = nullptr;
  I.npixels = 0;
  I.width = 0;
  I.height = 0;
  I.row = nullptr;
  I.hasOwnership = false;
}
#endif

template <class Type> void vpImage<Type>::insert(const vpImage<Type> &src, const vpImagePoint &topLeft)
{
  int itl = static_cast<int>(topLeft.get_i());
  int jtl = static_cast<int>(topLeft.get_j());
 
  int dest_ibegin = 0;
  int dest_jbegin = 0;
  int src_ibegin = 0;
  int src_jbegin = 0;
  int dest_w = static_cast<int>(this->getWidth());
  int dest_h = static_cast<int>(this->getHeight());
  int src_w = static_cast<int>(src.getWidth());
  int src_h = static_cast<int>(src.getHeight());
  int wsize = static_cast<int>(src.getWidth());
  int hsize = static_cast<int>(src.getHeight());
 
  if ((itl >= dest_h) || (jtl >= dest_w)) {
    return;
  }
 
  if (itl < 0) {
    src_ibegin = -itl;
  }
  else {
    dest_ibegin = itl;
  }
 
  if (jtl < 0) {
    src_jbegin = -jtl;
  }
  else {
    dest_jbegin = jtl;
  }
 
  if ((src_w - src_jbegin) >(dest_w - dest_jbegin)) {
    wsize = dest_w - dest_jbegin;
  }
  else {
    wsize = src_w - src_jbegin;
  }
 
  if ((src_h - src_ibegin) > (dest_h - dest_ibegin)) {
    hsize = dest_h - dest_ibegin;
  }
  else {
    hsize = src_h - src_ibegin;
  }
 
  for (int i = 0; i < hsize; ++i) {
    Type *srcBitmap = src.bitmap + (((src_ibegin + i) * src_w) + src_jbegin);
    Type *destBitmap = this->bitmap + (((dest_ibegin + i) * dest_w) + dest_jbegin);
 
    memcpy(static_cast<void *>(destBitmap), static_cast<void *>(srcBitmap), static_cast<size_t>(wsize) * sizeof(Type));
  }
}

template <class Type> void vpImage<Type>::halfSizeImage(vpImage<Type> &res) const
{
  unsigned int h = height / 2;
  unsigned int w = width / 2;
  res.resize(h, w);
  for (unsigned int i = 0; i < h; ++i) {
    for (unsigned int j = 0; j < w; ++j) {
      res[i][j] = (*this)[i << 1][j << 1];
    }
  }
}

template <class Type>
void vpImage<Type>::subsample(unsigned int v_scale, unsigned int h_scale, vpImage<Type> &sampled) const
{
  if ((v_scale == 1) && (h_scale == 1)) {
    sampled = *this;
    return;
  }
  unsigned int h = height / v_scale;
  unsigned int w = width / h_scale;
  sampled.resize(h, w);
  for (unsigned int i = 0; i < h; ++i) {
    for (unsigned int j = 0; j < w; ++j) {
      sampled[i][j] = (*this)[i * v_scale][j * h_scale];
    }
  }
}

template <class Type> void vpImage<Type>::quarterSizeImage(vpImage<Type> &res) const
{
  unsigned int h = height / 4;
  unsigned int w = width / 4;
  const unsigned int magic_2 = 2;
  res.resize(h, w);
  for (unsigned int i = 0; i < h; ++i) {
    for (unsigned int j = 0; j < w; ++j) {
      res[i][j] = (*this)[i << magic_2][j << magic_2];
    }
  }
}

template <class Type> void vpImage<Type>::doubleSizeImage(vpImage<Type> &res)
{
  const unsigned int magic_2 = 2;
  unsigned int h = height * magic_2;
  unsigned int w = width * magic_2;
 
  res.resize(h, w);
 
  for (unsigned int i = 0; i < h; ++i) {
    for (unsigned int j = 0; j < w; ++j) {
      res[i][j] = (*this)[i >> 1][j >> 1];
    }
  }
 
  /*
    A B C
    E F G
    H I J
    A C H J are pixels from original image
    B E G I are interpolated pixels
  */
 
  // interpolate pixels B and I
  for (unsigned int i = 0; i < h; i += magic_2) {
    for (unsigned int j = 1; j < (w - 1); j += magic_2) {
      res[i][j] = static_cast<Type>(0.5 * ((*this)[i >> 1][j >> 1] + (*this)[i >> 1][(j >> 1) + 1]));
    }
  }
 
  // interpolate pixels E and G
  for (unsigned int i = 1; i < (h - 1); i += magic_2) {
    for (unsigned int j = 0; j < w; j += magic_2) {
      res[i][j] = static_cast<Type>(0.5 * ((*this)[i >> 1][j >> 1] + (*this)[(i >> 1) + 1][j >> 1]));
    }
  }
 
  // interpolate pixel F
  for (unsigned int i = 1; i < (h - 1); i += magic_2) {
    for (unsigned int j = 1; j < (w - 1); j += magic_2) {
      res[i][j] = static_cast<Type>(0.25 * ((*this)[i >> 1][j >> 1] + (*this)[i >> 1][(j >> 1) + 1] +
                                            (*this)[(i >> 1) + 1][j >> 1] + (*this)[(i >> 1) + 1][(j >> 1) + 1]));
    }
  }
}

template <class Type> void vpImage<Type>::sub(const vpImage<Type> &B, vpImage<Type> &C) const
{
 
  try {
    if ((this->getHeight() != C.getHeight()) || (this->getWidth() != C.getWidth())) {
      C.resize(this->getHeight(), this->getWidth());
    }
  }
  catch (const vpException &me) {
    std::cout << me << std::endl;
    throw;
  }
 
  if ((this->getWidth() != B.getWidth()) || (this->getHeight() != B.getHeight())) {
    throw(vpException(vpException::memoryAllocationError, "vpImage mismatch in vpImage/vpImage subtraction"));
  }
 
  unsigned int this_width = this->getWidth();
  unsigned int this_height = this->getHeight();
  for (unsigned int i = 0; i < (this_width * this_height); ++i) {
    *(C.bitmap + i) = *(bitmap + i) - *(B.bitmap + i);
  }
}

template <class Type> void vpImage<Type>::sub(const vpImage<Type> &A, const vpImage<Type> &B, vpImage<Type> &C) const
{
 
  try {
    if ((A.getHeight() != C.getHeight()) || (A.getWidth() != C.getWidth())) {
      C.resize(A.getHeight(), A.getWidth());
    }
  }
  catch (const vpException &me) {
    std::cout << me << std::endl;
    throw;
  }
 
  if ((A.getWidth() != B.getWidth()) || (A.getHeight() != B.getHeight())) {
    throw(vpException(vpException::memoryAllocationError, "vpImage mismatch in vpImage/vpImage subtraction "));
  }
 
  unsigned int a_width = A.getWidth();
  unsigned int a_height = A.getHeight();
  for (unsigned int i = 0; i < (a_width * a_height); ++i) {
    *(C.bitmap + i) = *(A.bitmap + i) - *(B.bitmap + i);
  }
}
 
END_VISP_NAMESPACE
#endif