mlpack 4.6.2__cp38-cp38-win_amd64.whl → 4.7.0__cp38-cp38-win_amd64.whl

mlpack/include/mlpack/core/data/image_bounding_box_impl.hpp

@@ -0,0 +1,155 @@
+/**
+ * @file core/data/image_bounding_box_impl.hpp
+ * @author Andrew Furey
+ *
+ * Draw bounding boxes and labels onto images.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+
+#ifndef MLPACK_CORE_DATA_IMAGE_BOUNDING_BOX_IMPL_HPP
+#define MLPACK_CORE_DATA_IMAGE_BOUNDING_BOX_IMPL_HPP
+
+#include "image_bounding_box.hpp"
+#include "image_options.hpp"
+
+namespace mlpack {
+
+template <typename ImageType, typename ColorType>
+inline void UpdatePixel(ImageType& src,
+  const ImageInfo& opts,
+  const size_t x,
+  const size_t y,
+  const ColorType& color)
+{
+  const size_t redChannel =
+    x * opts.Channels() + y * opts.Channels() * opts.Width();
+  src.rows(redChannel, redChannel + color.n_rows - 1) =  color;
+}
+
+template <typename MatType>
+inline void DrawLetter(MatType& src,
+  const ImageInfo& opts,
+  const char letter,
+  const typename MatType::elem_type x,
+  const typename MatType::elem_type y,
+  const size_t size)
+{
+  const size_t fontWidth = 8;
+  for (size_t i = 0; i < fontWidth; i++)
+  {
+    for (size_t j = 0; j < fontWidth; j++)
+    {
+      const double on =
+        !(font8x8Basic[(size_t)letter][i] & (unsigned char)(1 << j));
+      const MatType set =
+        arma::repmat(MatType({ on * 255.0 }), opts.Channels(), 1);
+      for (size_t k = 0; k < size * size; k++)
+      {
+        const size_t px = x + (j * size) + (k % size);
+        const size_t py = y + (i * size) + (k / size);
+        UpdatePixel(src, opts, px, py, set);
+      }
+    }
+  }
+}
+
+template <typename ImageType,
+          typename BoundingBoxesType,
+          typename ColorType>
+inline void BoundingBoxImage(ImageType& src,
+  const ImageInfo& opts,
+  const BoundingBoxesType& bbox,
+  const ColorType& color,
+  const size_t borderSize,
+  const std::string& className,
+  const size_t letterSize)
+{
+  using ElemType = typename BoundingBoxesType::elem_type;
+
+  const size_t imageSize = opts.Width() * opts.Height() * opts.Channels();
+  if (src.n_elem != imageSize) {
+    std::ostringstream errMessage;
+    errMessage << "BoundingBoxImage(): The size of the image (" << src.n_elem
+               << ") does not match the given dimensions ("
+               << opts.Width() << ", " << opts.Height() << ", "
+               << opts.Channels() << ").";
+    throw std::logic_error(errMessage.str());
+  }
+
+  if (color.n_rows != opts.Channels() || color.n_cols != 1) {
+    std::ostringstream errMessage;
+    errMessage << "BoundingBoxImage(): The color vector of shape ("
+               << color.n_rows << ", " << color.n_cols << ") does not match "
+               << "expected shape (" << opts.Channels() << ", 1)";
+    throw std::logic_error(errMessage.str());
+  }
+
+  if (bbox.n_rows < 4) {
+    std::ostringstream errMessage;
+    errMessage << "BoundingBoxImage(): A bounding box is made up of 4 points "
+               "but was given " << color.n_rows;
+    throw std::logic_error(errMessage.str());
+  }
+
+  const ElemType maxWidth = opts.Width() - 1;
+  const ElemType maxHeight = opts.Height() - 1;
+  const ElemType x1 = std::clamp<ElemType>(bbox(0), 0, maxWidth);
+  const ElemType y1 = std::clamp<ElemType>(bbox(1), 0, maxHeight);
+  const ElemType x2 = std::clamp<ElemType>(bbox(2), 0, maxWidth);
+  const ElemType y2 = std::clamp<ElemType>(bbox(3), 0, maxHeight);
+
+  if (x1 >= x2)
+  {
+    std::ostringstream errMessage;
+    errMessage << "BoundingBoxImage(): x1 should be < x2, but "
+               << x1 << " >= " << x2;
+    throw std::logic_error(errMessage.str());
+  }
+
+  if (y1 >= y2)
+  {
+    std::ostringstream errMessage;
+    errMessage << "BoundingBoxImage(): y1 should be < y2, but "
+               << y1 << " >= " << y2;
+    throw std::logic_error(errMessage.str());
+  }
+
+  for (size_t b = 0; b < borderSize; b++)
+  {
+    for (size_t x = x1; x <= x2; x++)
+    {
+      const size_t yTop = y1 + b;
+      const size_t yBottom = y2 - b;
+      UpdatePixel(src, opts, x, yTop, color);
+      UpdatePixel(src, opts, x, yBottom, color);
+    }
+    for (int y = y1; y <= y2; y++)
+    {
+      const size_t xLeft = x1 + b;
+      const size_t xRight = x2 - b;
+      UpdatePixel(src, opts, xLeft, y, color);
+      UpdatePixel(src, opts, xRight, y, color);
+    }
+  }
+
+  // Draw class name
+  if (letterSize == 0)
+    return;
+  size_t dx = x1;
+  const ElemType update = letterSize * 8;
+  for (size_t i = 0; i < className.size(); i++)
+  {
+    if (dx + update > opts.Width())
+      break;
+    DrawLetter(src, opts, className[i], dx, y1, letterSize);
+    dx += update;
+  }
+}
+
+} // namespace mlpack
+
+#endif

mlpack/include/mlpack/core/data/image_layout.hpp

@@ -0,0 +1,63 @@
+/**
+ * @file core/data/image_layout.hpp
+ * @author Andrew Furey
+ *
+ * Image layout conversion utility functions.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+
+#ifndef MLPACK_CORE_DATA_IMAGE_LAYOUT_HPP
+#define MLPACK_CORE_DATA_IMAGE_LAYOUT_HPP
+
+#include "image_options.hpp"
+
+namespace mlpack {
+
+/**
+ * `Load()` returns a matrix where each column represents an image.
+ * The rows of each image represent pixel values whose channels are
+ * interleaved, i.e. [r, g, b, r, g, b, ... ]. Some mlpack functionality
+ * such as convolutions require that each channel of the image be grouped
+ * together instead, i.e. [r, r, ... , g, g, ... , b, b].
+ *
+ * 'GroupChannels()` makes a copy of the image and returns the same image
+ * except the channels are grouped together instead of interleaved.
+ * 
+ * `GroupChannels()` expects that your input image is stored such that channels
+ * are interleaved, i.e. [r, g, b, r, g, b ... ], and will not work as
+ * intended otherwise.
+ *
+ * @param image Image matrix whose channels are interleaved.
+ * @param info  ImageInfo describing shape of image.
+ * @return Mat  Copy of image whose channels are grouped together.
+ */
+template <typename eT>
+inline arma::Mat<eT> GroupChannels(const arma::Mat<eT>& image,
+    const ImageInfo& info);
+
+/**
+ * The inverse of `GroupChannels()`. Given an image where each channel is
+ * grouped together, make a copy and interleave the channels,
+ * i.e. [r, g, b, r, g, b, ... ].
+ *
+ * `InterleaveChannels()` expects that your input image is stored such that
+ * the channels are grouped, i.e. [r, r, ..., g, g, ..., b, b], and will not
+ * work as intended otherwise.
+ *
+ * @param image Image matrix in mlpack layout.
+ * @param info  ImageInfo describing shape of image.
+ * @return Mat  Copy of image whose channels are interleaved.
+ */
+template <typename eT>
+inline arma::Mat<eT> InterleaveChannels(const arma::Mat<eT>& image,
+    const ImageInfo& info);
+
+} // namespace mlpack
+
+#include "image_layout_impl.hpp"
+
+#endif

mlpack/include/mlpack/core/data/image_layout_impl.hpp

@@ -0,0 +1,75 @@
+/**
+ * @file core/data/image_layout_impl.hpp
+ * @author Andrew Furey
+ *
+ * Convert image layouts between mlpack and stb.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+
+#ifndef MLPACK_CORE_DATA_IMAGE_LAYOUT_IMPL_HPP
+#define MLPACK_CORE_DATA_IMAGE_LAYOUT_IMPL_HPP
+
+#include "image_layout.hpp"
+#include "image_options.hpp"
+
+namespace mlpack {
+
+template <typename eT>
+arma::Mat<eT> GroupChannels(const arma::Mat<eT>& image,
+    const ImageInfo& info)
+{
+  size_t expectedRows = info.Width() * info.Height() * info.Channels();
+  if (expectedRows != image.n_rows)
+  {
+    std::ostringstream errMessage;
+    errMessage << "GroupChannels(): Expected " << expectedRows
+               << " rows but got image with " << image.n_rows << " rows.";
+    throw std::logic_error(errMessage.str());
+  }
+
+  if (info.Channels() == 1)
+    return image;
+
+  arma::Mat<eT> output(image.n_rows, image.n_cols, arma::fill::none);
+  for (size_t i = 0; i < image.n_cols; i++)
+  {
+    output.col(i) = arma::vectorise(
+      arma::reshape(image.col(i), info.Channels(), info.Height() * info.Width())
+        .t());
+  }
+  return output;
+}
+
+template <typename eT>
+arma::Mat<eT> InterleaveChannels(const arma::Mat<eT>& image,
+    const ImageInfo& info)
+{
+  size_t expectedRows = info.Width() * info.Height() * info.Channels();
+  if (expectedRows != image.n_rows)
+  {
+    std::ostringstream errMessage;
+    errMessage << "InterleaveChannels(): Expected " << expectedRows
+               << " rows but got image with " << image.n_rows << " rows.";
+    throw std::logic_error(errMessage.str());
+  }
+
+  if (info.Channels() == 1)
+    return image;
+
+  arma::Mat<eT> output(image.n_rows, image.n_cols);
+  for (size_t i = 0; i < image.n_cols; i++)
+  {
+    output.col(i) = arma::vectorise(
+      arma::reshape(image.col(i), info.Height() * info.Width(), info.Channels())
+        .t());
+  }
+  return output;
+}
+
+} // namespace mlpack
+
+#endif

mlpack/include/mlpack/core/data/image_letterbox.hpp

@@ -0,0 +1,116 @@
+/**
+ * @file core/data/image_letterbox.hpp
+ * @author Andrew Furey
+ *
+ * Apply letterbox transform to an image.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+
+#ifndef MLPACK_CORE_DATA_IMAGE_LETTERBOX_HPP
+#define MLPACK_CORE_DATA_IMAGE_LETTERBOX_HPP
+
+#include <mlpack/prereqs.hpp>
+
+#include "image_options.hpp"
+#include "image_resize_crop.hpp"
+
+namespace mlpack {
+
+/**
+ * Resize an image to `imgSize` x `imgSize` while keeping the original
+ * image's aspect ratio. Fill in white space with `fillValue`.
+ *
+ * @param src The source matrix that contains the images.
+ * @param srcOpt Contains relevant information on each source image.
+ * @param dest The destination matrix that will have the source image
+          embedded onto it
+ * @param imgSize The width and height of each output image.
+ * @param fillValue The whitespace value.
+ */
+template<typename eT>
+void LetterboxImages(arma::Mat<eT>& src,
+                    ImageOptions& srcOpt,
+                    const size_t width,
+                    const size_t height,
+                    const eT fillValue)
+{
+  const size_t expectedRows =
+    srcOpt.Width() * srcOpt.Height() * srcOpt.Channels();
+
+  if (expectedRows == 0)
+  {
+    std::ostringstream errMessage;
+    errMessage << "LetterboxImages(): Dimensions cannot contain a zero."
+      " Received: " << srcOpt.Width() << " x " << srcOpt.Height()
+      << " x " << srcOpt.Channels() << ".";
+    throw std::logic_error(errMessage.str());
+  }
+
+  if (src.n_rows == 0)
+    throw std::logic_error("LetterboxImages(): Matrix rows cannot be zero.");
+
+  if (src.n_rows != expectedRows)
+  {
+    std::ostringstream errMessage;
+    errMessage << "LetterboxImages(): Expected size of image was "
+      << expectedRows << " but received " << src.n_rows;
+    throw std::logic_error(errMessage.str());
+  }
+
+  if (srcOpt.Channels() != 1 && srcOpt.Channels() != 3)
+  {
+    std::ostringstream errMessage;
+    errMessage << "LetterboxImages(): Must have only 1 or 3 channels, but "
+      "received " << srcOpt.Channels();
+    throw std::logic_error(errMessage.str());
+  }
+
+  size_t newWidth, newHeight;
+  if (width * 1. / srcOpt.Width() > height * 1. / srcOpt.Height())
+  {
+    newHeight = height;
+    newWidth = srcOpt.Width() * height / srcOpt.Height();
+  }
+  else
+  {
+    newWidth = width;
+    newHeight = srcOpt.Height() * width / srcOpt.Width();
+  }
+
+  const size_t numImages = src.n_cols;
+  arma::Mat<eT> dest(width * height * srcOpt.Channels(), numImages,
+                     arma::fill::none);
+
+  // Resize, then embed src within dest.
+  ResizeImages(src, srcOpt, newWidth, newHeight);
+  arma::Cube<eT> cubeSrc, cubeDest;
+
+  // Channels as rows, because assumption is that channels are
+  // interleaved (see image_layout.hpp for more info).
+  MakeAlias(cubeSrc, src, srcOpt.Channels() * srcOpt.Width(), srcOpt.Height(),
+            numImages);
+  MakeAlias(cubeDest, dest, srcOpt.Channels() * width, height, numImages);
+
+  const size_t dx = (width - newWidth) / 2;
+  const size_t dy = (height - newHeight) / 2;
+
+  cubeDest.fill(fillValue);
+  // Fill RGB
+  cubeDest.subcube(dx * srcOpt.Channels(),
+                   dy,
+                   0,
+                   ((srcOpt.Width() + dx) * srcOpt.Channels()) - 1,
+                   srcOpt.Height() + dy - 1,
+                   numImages - 1) = cubeSrc;
+
+  src = std::move(dest);
+  srcOpt = ImageOptions(width, height, srcOpt.Channels());
+}
+
+} // namespace mlpack
+
+#endif

mlpack/include/mlpack/core/data/image_options.hpp

@@ -0,0 +1,257 @@
+/**
+ * @file core/data/image_options.hpp
+ * @author Mehul Kumar Nirala
+ * @author Ryan Curtin
+ * @author Omar Shrit
+ *
+ * Image options, all possible options to load different image formats
+ * with specific settings into mlpack.
+ *
+ * mlpack is free software; you may redistribute it and/or modify it under the
+ * terms of the 3-clause BSD license.  You should have received a copy of the
+ * 3-clause BSD license along with mlpack.  If not, see
+ * http://www.opensource.org/licenses/BSD-3-Clause for more information.
+ */
+
+#ifndef MLPACK_CORE_DATA_IMAGE_INFO_HPP
+#define MLPACK_CORE_DATA_IMAGE_INFO_HPP
+
+#include <mlpack/prereqs.hpp>
+#include "extension.hpp"
+#include "data_options.hpp"
+
+namespace mlpack {
+
+/**
+ * Implements meta-data of images required by Load and
+ * Save for loading and saving images into arma::Mat.
+ */
+class ImageOptions : public DataOptionsBase<ImageOptions>
+{
+ public:
+  /**
+   * Instantiate the ImageOptions object with the given image width, height,
+   * number of channels and quality parameter.
+   *
+   * @param width Image width.
+   * @param height Image height.
+   * @param channels Number of channels in the image.
+   * @param quality Compression of the image if saved as jpg (0 - 100).
+   * #param image Indicate if we are loading / saving an image. 
+   */
+  ImageOptions(std::optional<size_t> width = std::nullopt,
+               std::optional<size_t> height = std::nullopt,
+               std::optional<size_t> channels = std::nullopt,
+               std::optional<size_t> quality = std::nullopt) :
+    DataOptionsBase<ImageOptions>(),
+    width(width),
+    height(height),
+    channels(channels),
+    quality(quality)
+  {
+    // Do nothing.
+  }
+
+  ImageOptions(const DataOptionsBase<ImageOptions>& opts) :
+      DataOptionsBase<ImageOptions>()
+  {
+    // Delegate to copy operator.
+    *this = opts;
+  }
+
+  ImageOptions(DataOptionsBase<ImageOptions>&& opts) :
+      DataOptionsBase<ImageOptions>()
+  {
+    // Delegate to move operator.
+    *this = std::move(opts);
+  }
+
+  ImageOptions& operator=(const DataOptionsBase<ImageOptions>& otherIn)
+  {
+    const ImageOptions& other = static_cast<const ImageOptions&>(otherIn);
+
+    if (&other == this)
+      return *this;
+
+    width    = other.width;
+    height   = other.height;
+    channels = other.channels;
+    quality  = other.quality;
+
+    // Copy base members.
+    DataOptionsBase<ImageOptions>::operator=(other);
+
+    return *this;
+  }
+
+  ImageOptions& operator=(DataOptionsBase<ImageOptions>&& otherIn)
+  {
+    ImageOptions&& other = static_cast<ImageOptions&&>(otherIn);
+
+    if (&other == this)
+      return *this;
+
+    width    = std::move(other.width);
+    height   = std::move(other.height);
+    channels = std::move(other.channels);
+    quality  = std::move(other.quality);
+
+    // Move base members.
+    DataOptionsBase<ImageOptions>::operator=(std::move(other));
+
+    return *this;
+  }
+
+  //
+  // Handling for copy and move operations on other DataOptionsBase types.
+  //
+
+  // Conversions must be explicit.
+  template<typename Derived2>
+  explicit ImageOptions(const DataOptionsBase<Derived2>& other) :
+      DataOptionsBase<ImageOptions>(other) { }
+
+  template<typename Derived2>
+  explicit ImageOptions(DataOptionsBase<Derived2>&& other) :
+      DataOptionsBase<ImageOptions>(std::move(other)) { }
+
+  template<typename Derived2>
+  ImageOptions& operator=(const DataOptionsBase<Derived2>& other)
+  {
+    return static_cast<ImageOptions&>(
+        DataOptionsBase<ImageOptions>::operator=(other));
+  }
+
+  template<typename Derived2>
+  ImageOptions& operator=(DataOptionsBase<Derived2>&& other)
+  {
+    return static_cast<ImageOptions&>(
+        DataOptionsBase<ImageOptions>::operator=(std::move(other)));
+  }
+
+  void Combine(const ImageOptions& other)
+  {
+    if (!width.has_value() && other.width.has_value())
+    {
+      width = other.width;
+    }
+    else if (width.has_value() && other.width.has_value())
+    {
+      if (width.has_value() != other.width.has_value())
+      {
+        throw std::invalid_argument("ImageOptions: operator+(): cannot combine"
+            "width with different values!");
+      }
+    }
+
+    if (!height.has_value() && other.height.has_value())
+    {
+      height = other.height;
+    }
+    else if (height.has_value() && other.height.has_value())
+    {
+      if (height.has_value() != other.height.has_value())
+      {
+        throw std::invalid_argument("ImageOptions: operator+(): cannot combine"
+            "height with different values!");
+      }
+    }
+
+    if (!channels.has_value() && other.channels.has_value())
+    {
+      channels = other.channels;
+    }
+    else if (channels.has_value() && other.channels.has_value())
+    {
+      if (channels.has_value() != other.channels.has_value())
+      {
+        throw std::invalid_argument("ImageOptions: operator+(): cannot combine"
+            "channels with different values!");
+      }
+    }
+
+    if (!quality.has_value() && other.quality.has_value())
+    {
+      quality = other.quality;
+    }
+    else if (quality.has_value() && other.quality.has_value())
+    {
+      if (quality.has_value() != other.quality.has_value())
+      {
+        throw std::invalid_argument("ImageOptions: operator+(): cannot combine"
+            "quality with different values!");
+      }
+    }
+  }
+
+  // Print warnings for any members that cannot be represented by a
+  // DataOptionsBase<void>.
+  void WarnBaseConversion(const char* dataDescription) const
+  {
+    if (width.has_value() && width != defaultWidth)
+      this->WarnOptionConversion("width", dataDescription);
+    if (height.has_value() && height != defaultHeight)
+      this->WarnOptionConversion("height", dataDescription);
+    if (channels.has_value() && channels != defaultChannels)
+      this->WarnOptionConversion("channels", dataDescription);
+    if (quality.has_value() && quality != defaultQuality)
+      this->WarnOptionConversion("quality", dataDescription);
+  }
+
+  static const char* DataDescription() { return "image data"; }
+
+  void Reset()
+  {
+    width.reset();
+    height.reset();
+    channels.reset();
+    quality.reset();
+  }
+
+  size_t Width() const { return this->AccessMember(width, defaultWidth); }
+  size_t& Width() { return this->ModifyMember(width, defaultWidth); }
+
+  size_t Height() const { return this->AccessMember(height, defaultHeight); }
+  size_t& Height() { return this->ModifyMember(height, defaultHeight); }
+
+  size_t Channels() const
+  {
+    return this->AccessMember(channels, defaultChannels);
+  }
+
+  size_t& Channels() { return this->ModifyMember(channels, defaultChannels); }
+
+  size_t Quality() const { return this->AccessMember(quality, defaultQuality); }
+  size_t& Quality() { return this->ModifyMember(quality, defaultQuality); }
+
+  inline static const std::unordered_set<std::string> saveType
+      = {"jpg", "png", "tga", "bmp"};
+
+  inline static const std::unordered_set<std::string> loadType
+      = {"jpg", "png", "tga", "bmp", "psd", "gif", "pic", "pnm", "jpeg"};
+
+ private:
+  std::optional<size_t> width;
+  std::optional<size_t> height;
+  std::optional<size_t> channels;
+  std::optional<size_t> quality;
+
+  constexpr static const size_t defaultWidth = 0;
+  constexpr static const size_t defaultHeight = 0;
+  constexpr static const size_t defaultChannels = 3;
+  constexpr static const size_t defaultQuality = 90;
+};
+
+template<>
+struct IsDataOptions<ImageOptions>
+{
+  constexpr static bool value = true;
+};
+
+// Provide backward compatibility with the previous API
+// This should be removed with mlpack 5.0.0
+using ImageInfo = ImageOptions;
+
+} // namespace mlpack
+
+#endif