Face Engine SDK  5.6.0
A face detection, recognition and tracking engine.
Image.h
1 #pragma once
2 
3 #include <fsdk/Def.h>
4 #include <fsdk/Types/Format.h>
5 #include <fsdk/Types/Rect.h>
6 #include <fsdk/Types/Result.h>
7 #include <fsdk/Types/Sizer.h>
8 #include <fsdk/Types/SubImage.h>
9 
10 namespace fsdk
11 {
12 
13  struct IArchive;
14 
38  struct Image {
39 
43  enum class Type: uint8_t {
44  BMP,
45  JPG,
46  PNG,
47  PPM,
48  TIFF,
49  Unknown
50  };
51 
55  enum class TargetDevice {
56  CPU,
57  GPU,
58  NPU,
59  };
60 
67  enum class ImageCompression {
73  };
77  enum class Error: uint32_t {
78  Ok,
79  InvalidWidth,
83  InvalidImage,
85  InvalidPath,
86  InvalidType,
93  FailedToSave,
94  FailedToLoad,
97  };
98 
104  enum class MemoryResidence: uint32_t {
105  MemoryCPU,
106  MemoryGPU,
107  MemoryNPU,
108  MemoryNPU_DPP,
109  };
110 
113  FSDK_API Image() noexcept;
114 
124  int width,
125  int height,
126  Format format,
127  MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
128 
140  int width,
141  int height,
142  Format format,
143  const void* data,
144  MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
145 
162  int width,
163  int height,
164  Format format,
165  void* data,
166  bool copy,
167  MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
168 
173  FSDK_API Image(const Image& other) noexcept;
174 
179  FSDK_API Image(Image&& other) noexcept;
180 
186  FSDK_API explicit Image(const SubImage& subImage) noexcept;
187 
188  FSDK_API ~Image();
189 
202  FSDK_API Result<Error> create(int width, int height, Format format, bool cleanup = true, MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
203 
217  FSDK_API Result<Error> create(int width, int height, Format format, const void* data, MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
218 
236  FSDK_API Result<Error> create(int width, int height, Format format, void* data, bool copy, MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
237 
245  FSDK_API Result<Error> create(const fsdk::Image& source, MemoryResidence residence) noexcept;
246 
263  int width,
264  int height,
265  Format format,
266  const void* data,
267  MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
268 
289  int width,
290  int height,
291  Format format,
292  void* data,
293  bool copy,
294  MemoryResidence residence = MemoryResidence::MemoryCPU) noexcept;
295 
301  FSDK_API Result<Error> set(const Image& other) noexcept;
302 
308  FSDK_API Result<Error> set(const SubImage& subImage) noexcept;
309 
322  FSDK_API SubImage map(int x, int y, int width, int height) const noexcept;
323 
331  SubImage map(const Rect& rect) const noexcept {
332  return map(rect.x, rect.y, rect.width, rect.height);
333  }
334 
344  SubImage map(const Size& size) const noexcept {
345  return map(Point2i(0, 0), size);
346  }
347 
356  SubImage map(const Point2i& origin, const Size& size) const noexcept {
357  return map(origin.x, origin.y, size.x, size.y);
358  }
359 
373  FSDK_API Image extract(int x, int y, int width, int height) const noexcept;
374 
383  Image extract(const Rect& rect) const noexcept {
384  return extract(rect.x, rect.y, rect.width, rect.height);
385  }
386 
397  Image extract(const Size& size) const noexcept {
398  return extract(Point2i(0, 0), size);
399  }
400 
410  Image extract(const Point2i& origin, const Size& size) const noexcept {
411  return extract(origin.x, origin.y, size.x, size.y);
412  }
413 
421  FSDK_API static Result<Error> guessTypeFromMemory(const void* data, const uint32_t sizeInBytes, Type& type) noexcept;
422 
428  Image clone() const noexcept {
429  return Image(
430  getWidth(),
431  getHeight(),
432  getFormat(),
433  getData());
434  }
435 
454  FSDK_API Result<Image::Error> convert(Image& dest, int x, int y, int width, int height, Format format, TargetDevice device = TargetDevice::CPU) const noexcept;
455 
470  Result<Image::Error> convert(Image& dest, const Point2i& origin, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
471  return convert(dest, origin.x, origin.y, size.x, size.y, format, device);
472  }
473 
489  Result<Image::Error> convert(Image& dest, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
490  return convert(dest, Point2i(0, 0), size, format, device);
491  }
492 
506  Result<Image::Error> convert(Image& dest, const Rect& rect, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
507  return convert(dest, rect.x, rect.y, rect.width, rect.height, format, device);
508  }
509 
520  Result<Image::Error> convert(Image& dest, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
521  return convert(dest, getRect(), format, device);
522  }
523 
529  FSDK_API Image rescale(float scale) const noexcept;
530 
542  fsdk::Image::ImageCompression additionalFlag =
544 
556  const char* path,
557  const Format format) const noexcept;
558 
571  IArchive* archive,
573 
586  Image::Type type,
587  IArchive* archive,
588  const Format format) const noexcept;
589 
602  FSDK_API Result<Error> load(const char* path) noexcept;
603 
614  const char* path,
615  const Format format) noexcept;
616 
631  const void* data,
632  const uint32_t sizeInBytes) noexcept;
633 
645  const void* data,
646  const uint32_t sizeInBytes,
647  const Format format) noexcept;
648 
665  const void* data,
666  const uint32_t sizeInBytes,
667  const Type type) noexcept;
668 
681  const void* data,
682  const uint32_t sizeInBytes,
683  const Type type,
684  const Format format) noexcept;
685 
689  Image& operator = (const Image& other) noexcept {
690  set(other);
691 
692  return *this;
693  }
694 
698  Image& operator = (Image&& other) noexcept {
699  if(this != &other) {
700  release();
701  swap(other);
702  }
703 
704  return *this;
705  }
706 
708  bool isNull() const noexcept {
709  return getData() == nullptr;
710  }
711 
715  bool isValid() const noexcept {
716  return !isNull() &&
717  getHeight() > 0 &&
718  getWidth() > 0 &&
719  getFormat().isValid();
720  }
721 
725  operator bool () const noexcept {
726  return isValid();
727  }
728 
733  FSDK_API void* getScanLine(int y) noexcept;
734 
739  FSDK_API const void* getScanLine(int y) const noexcept;
740 
743  FSDK_API int getDataSize() const noexcept;
744 
748  FSDK_API void getDataSize(Sizer& sizer) const noexcept;
749 
754  template<typename T>
755  T* getScanLineAs(int y) noexcept {
756  return reinterpret_cast<T*>(getScanLine(y));
757  }
758 
763  template<typename T>
764  const T* getScanLineAs(int y) const noexcept {
765  return reinterpret_cast<const T*>(getScanLine(y));
766  }
767 
770  void* getData() noexcept {
771  return m_data;
772  }
773 
776  const void* getData() const noexcept {
777  return m_data;
778  }
779 
782  template<typename T>
783  T* getDataAs() noexcept {
784  return reinterpret_cast<T*>(getData());
785  }
786 
789  template<typename T>
790  const T* getDataAs() const noexcept {
791  return reinterpret_cast<const T*>(getData());
792  }
793 
795  int getRowSize() const noexcept {
796  return getFormat().computePitch(getWidth());
797  }
798 
800  int getWidth() const noexcept {
801  return m_width;
802  }
803 
805  int getHeight() const noexcept {
806  return m_height;
807  }
808 
810  float getAspectRatio() const noexcept {
811  return
812  static_cast<float>(getWidth()) /
813  static_cast<float>(getHeight());
814  }
815 
817  Format getFormat() const noexcept {
818  return m_format;
819  }
820 
821  MemoryResidence getMemoryResidence() const noexcept {
822  return m_residence;
823  }
824 
826  Size getSize() const noexcept {
827  return Size(getWidth(), getHeight());
828  }
829 
833  Rect getRect() const noexcept {
834  return Rect(0, 0, getWidth(), getHeight());
835  }
836 
841  bool ownsData() const noexcept {
842  return !!m_ref;
843  }
844 
849  bool isSharedWith(const Image& other) const noexcept {
850  return getData() == other.getData();
851  }
852 
856  void swap(Image& other) noexcept {
857  std::swap(m_data, other.m_data);
858  std::swap(m_ref, other.m_ref);
859  std::swap(m_height, other.m_height);
860  std::swap(m_width, other.m_width);
861  std::swap(m_format, other.m_format);
862  std::swap(m_residence, other.m_residence);
863  }
864 
867  void reset() noexcept {
868  Image().swap(*this);
869  }
870 
876  bool equalWeak(const fsdk::Image& other) noexcept {
877  return
878  m_width == other.getWidth() &&
879  m_height == other.getHeight() &&
880  m_format == other.getFormat() &&
881  m_residence == other.getMemoryResidence();
882  }
883 
889  bool equalStrong(const fsdk::Image& other) noexcept {
890  return equalWeak(other) && m_data == other.getData();
891  }
892 
893 
894  FSDK_API void putPixel(uint32_t x, uint32_t y) noexcept;
895 
896  protected:
897  void* m_data;
898  int* m_ref;
899  int m_height;
900  int m_width;
901 
903  MemoryResidence m_residence;
904 
909  FSDK_API static void* allocate(int size) noexcept;
910 
914  FSDK_API static void deallocate(void* memory) noexcept;
915 
919  FSDK_API int retain() noexcept;
920 
924  FSDK_API int release() noexcept;
925 
929  FSDK_API int getRefCount() const noexcept;
930  };
931 
935  template<>
937 
938  static bool isOk(Image::Error error) noexcept {
939  return error == Image::Error::Ok;
940  }
941 
942  static const char* toString (Image::Error error) noexcept {
943  switch(error) {
944  case Image::Error::Ok: return "Ok";
945  case Image::Error::InvalidType: return "Unsupported type";
946  case Image::Error::InvalidPath: return "Invalid path";
947  case Image::Error::FailedToSave: return "Error during image saving";
948  case Image::Error::FailedToLoad: return "Error during image loading";
949  case Image::Error::InvalidImage: return "Invalid image";
950  case Image::Error::InvalidWidth: return "Invalid image width";
951  case Image::Error::InvalidHeight: return "Invalid image height";
952  case Image::Error::InvalidFormat: return "Unsupported format";
953  case Image::Error::InvalidMemory: return "Memory error";
954  case Image::Error::InvalidBitmap: return "Bitmap error";
955  case Image::Error::InvalidArchive: return "Archive error";
956  case Image::Error::InvalidDataPtr: return "Bad input data pointer";
957  case Image::Error::InvalidDataSize: return "Bad input data size";
958  case Image::Error::InvalidConversion: return "Required conversion not implemented";
959  case Image::Error::InvalidDevice: return "Selected Target Device is not supported for this system";
960  case Image::Error::FailedToInitialize: return "Error during initialization";
961  case Image::Error::ReleasedInOtherThread: return "Failed to retain image: it was released in another thread.";
962  default: return "Unknown error";
963  }
964  }
965  };
966 
971  using ImageError = Image::Error;
974 
975 }
fsdk::Image::ownsData
bool ownsData() const noexcept
Definition: Image.h:841
fsdk::Image::m_width
int m_width
image width.
Definition: Image.h:900
fsdk::Image::m_height
int m_height
image height.
Definition: Image.h:899
fsdk::Image::getData
const void * getData() const noexcept
Definition: Image.h:776
fsdk::Image::getData
void * getData() noexcept
Definition: Image.h:770
fsdk::Image::MemoryResidence
MemoryResidence
Memory residence.
Definition: Image.h:104
fsdk::Image::getSize
Size getSize() const noexcept
Definition: Image.h:826
fsdk::Image::m_format
Format m_format
image format (
Definition: Image.h:902
fsdk::Image::loadFromMemory
FSDK_API Result< Error > loadFromMemory(const void *data, const uint32_t sizeInBytes) noexcept
Load image from memory.
fsdk::Image::MemoryResidence::MemoryCPU
@ MemoryCPU
Image in Host device memory.
fsdk::Image::Error::InvalidConversion
@ InvalidConversion
Conversion not implemented.
fsdk::Image::convert
FSDK_API Result< Image::Error > convert(Image &dest, int x, int y, int width, int height, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
fsdk::Image::ImageCompression::IC_BEST_COMPRESSION
@ IC_BEST_COMPRESSION
maximum compression level (only for png or jpg)
fsdk::Image::map
FSDK_API SubImage map(int x, int y, int width, int height) const noexcept
Map image contents to a given area.
fsdk::Image::Error::InvalidDataPtr
@ InvalidDataPtr
Bad input data pointer.
fsdk::Image::load
FSDK_API Result< Error > load(const char *path) noexcept
Load image from file.
fsdk::Image::convert
Result< Image::Error > convert(Image &dest, const Rect &rect, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:506
fsdk::Image::convert
Result< Image::Error > convert(Image &dest, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:489
fsdk::Image::Error::FailedToInitialize
@ FailedToInitialize
Error during initialization.
fsdk::Vector2< int >
fsdk::Image::getHeight
int getHeight() const noexcept
Definition: Image.h:805
fsdk::Image::swap
void swap(Image &other) noexcept
Swap contents with another image.
Definition: Image.h:856
fsdk::Image::Error::InvalidHeight
@ InvalidHeight
Invalid height.
fsdk::Image::convert
Result< Image::Error > convert(Image &dest, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:520
fsdk::Image::Error::InvalidMemory
@ InvalidMemory
Error at memory opening.
fsdk::Image::getDataAs
const T * getDataAs() const noexcept
Definition: Image.h:790
fsdk::Image::isNull
bool isNull() const noexcept
Definition: Image.h:708
fsdk::Image::load
FSDK_API Result< Error > load(const char *path, const Format format) noexcept
Load image from file and convert it to required format.
fsdk
SDK namespace.
Definition: IAGSEstimator.h:8
fsdk::BaseRect< int >
fsdk::Image::getScanLineAs
T * getScanLineAs(int y) noexcept
Get image scanline data.
Definition: Image.h:755
fsdk::Image::operator=
Image & operator=(const Image &other) noexcept
Assign an other image.
Definition: Image.h:689
fsdk::Image::allocate
static FSDK_API void * allocate(int size) noexcept
Allocate memory.
fsdk::Image::extract
Image extract(const Rect &rect) const noexcept
Extract a sub image of this image. The new image will have it's own reference count.
Definition: Image.h:383
fsdk::Image::Error::InvalidDevice
@ InvalidDevice
Target Device is not supported for this system.
fsdk::Image::Error::InvalidPath
@ InvalidPath
Bad path for saving / loading.
fsdk::Image::Error::InvalidResidence
@ InvalidResidence
Invalid memory residence.
fsdk::Image::m_data
void * m_data
raw image data.
Definition: Image.h:897
fsdk::Image::Error::InvalidDataSize
@ InvalidDataSize
Bad input data size.
fsdk::Image::getDataAs
T * getDataAs() noexcept
Definition: Image.h:783
fsdk::Image::ImageCompression
ImageCompression
Supported compression type is used only for jpg and png types.
Definition: Image.h:67
fsdk::Image::clone
Image clone() const noexcept
Create a copy of this image. The new image will have it's own reference count.
Definition: Image.h:428
fsdk::Image::equalStrong
bool equalStrong(const fsdk::Image &other) noexcept
Performs strong comparison of this image with other. Beside weak comparison strong comparison also ch...
Definition: Image.h:889
fsdk::Image::equalWeak
bool equalWeak(const fsdk::Image &other) noexcept
Performs weak comparison of this image with other. Weak in this context means only image parameters s...
Definition: Image.h:876
fsdk::Image::isSharedWith
bool isSharedWith(const Image &other) const noexcept
Definition: Image.h:849
fsdk::Format
Image format.
Definition: Format.h:11
fsdk::Image::extract
Image extract(const Size &size) const noexcept
Extract a sub image of this image. The new image will have it's own reference count.
Definition: Image.h:397
fsdk::Image::loadFromMemoryOfType
FSDK_API Result< Error > loadFromMemoryOfType(const void *data, const uint32_t sizeInBytes, const Type type) noexcept
Load image from memory of specific type.
fsdk::Image::ImageCompression::IC_NO_COMPRESSION
@ IC_NO_COMPRESSION
no compression (only for png or jpg image)
fsdk::Image::getRowSize
int getRowSize() const noexcept
Definition: Image.h:795
fsdk::Format::computePitch
int computePitch(int rowWidth) const noexcept
Compute row size in bytes.
Definition: Format.h:121
fsdk::Format::isValid
bool isValid() const noexcept
Definition: Format.h:174
FSDK_API
#define FSDK_API
Dummy.
Definition: Def.h:27
fsdk::Image::loadFromMemory
FSDK_API Result< Error > loadFromMemory(const void *data, const uint32_t sizeInBytes, const Format format) noexcept
Load image from memory and convert it to required format.
fsdk::Image::MemoryResidence::MemoryNPU_DPP
@ MemoryNPU_DPP
Image in NPU PreProcessing module memory.
fsdk::Image::save
FSDK_API Result< Error > save(const char *path, const Format format) const noexcept
Convert and Save image.
fsdk::Image::getDataSize
FSDK_API int getDataSize() const noexcept
fsdk::Size
Vector2< int > Size
Definition: Vector2.h:299
fsdk::Image::getWidth
int getWidth() const noexcept
Definition: Image.h:800
fsdk::Image::saveToMemory
FSDK_API Result< Image::Error > saveToMemory(Image::Type type, IArchive *archive, fsdk::Image::ImageCompression additionalFlag=fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept
Save image to memory buffer.
fsdk::Image::ImageCompression::IC_HARD_COMPRESSION
@ IC_HARD_COMPRESSION
more than medium compression (only for png or jpg)
fsdk::Image::extract
FSDK_API Image extract(int x, int y, int width, int height) const noexcept
Extract a sub image of this image. The new image will have it's own reference count.
fsdk::Image::reset
void reset() noexcept
Reset image contents.
Definition: Image.h:867
fsdk::Image::loadFromMemoryOfType
FSDK_API Result< Error > loadFromMemoryOfType(const void *data, const uint32_t sizeInBytes, const Type type, const Format format) noexcept
Load image from memory of specific type and convert it to required format.
fsdk::Image::retain
FSDK_API int retain() noexcept
Increase reference count.
fsdk::Image::release
FSDK_API int release() noexcept
Decrease reference count.
fsdk::Image::convert
Result< Image::Error > convert(Image &dest, const Point2i &origin, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:470
fsdk::Image::Error::FailedToSave
@ FailedToSave
Error during image saving.
fsdk::Image::Error::InvalidImage
@ InvalidImage
Invalid image.
fsdk::Image::map
SubImage map(const Point2i &origin, const Size &size) const noexcept
Map image contents to a given area.
Definition: Image.h:356
fsdk::IArchive
Archive interface.
Definition: IObject.h:37
fsdk::Point2i
Vector2< int > Point2i
Definition: Vector2.h:290
fsdk::Image::extract
Image extract(const Point2i &origin, const Size &size) const noexcept
Extract a sub image of this image. The new image will have it's own reference count.
Definition: Image.h:410
fsdk::Image::Error::InvalidBitmap
@ InvalidBitmap
Bitmap error occurred.
fsdk::ErrorTraits
Definition: Result.h:10
fsdk::Image::create
FSDK_API Result< Error > create(int width, int height, Format format, bool cleanup=true, MemoryResidence residence=MemoryResidence::MemoryCPU) noexcept
Initializes an empty image and preallocates storage buffer of given size.
fsdk::Image::getAspectRatio
float getAspectRatio() const noexcept
Definition: Image.h:810
fsdk::Image::save
FSDK_API Result< Image::Error > save(const char *path, fsdk::Image::ImageCompression additionalFlag=fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept
Save image.
fsdk::Image::Image
FSDK_API Image() noexcept
Initializes an empty image.
fsdk::Image::MemoryResidence::MemoryNPU
@ MemoryNPU
Image in NPU device memory.
fsdk::Image::getRect
Rect getRect() const noexcept
Definition: Image.h:833
fsdk::Result
A structure that encapsulates an action result enumeration.
Definition: Result.h:30
fsdk::Image::deallocate
static FSDK_API void deallocate(void *memory) noexcept
Free memory.
fsdk::Image::rescale
FSDK_API Image rescale(float scale) const noexcept
Rescale image keeping proportions.
fsdk::Image::guessTypeFromMemory
static FSDK_API Result< Error > guessTypeFromMemory(const void *data, const uint32_t sizeInBytes, Type &type) noexcept
Guess type of image written into memory.
fsdk::Image::getFormat
Format getFormat() const noexcept
Definition: Image.h:817
fsdk::Image::isValid
bool isValid() const noexcept
Definition: Image.h:715
fsdk::Image::MemoryResidence::MemoryGPU
@ MemoryGPU
Image in Cuda device memory.
fsdk::Image::Error::Ok
@ Ok
Ok.
fsdk::Image::getScanLine
FSDK_API const void * getScanLine(int y) const noexcept
Get image scanline data.
fsdk::Image
Image.
Definition: Image.h:38
fsdk::Image::map
SubImage map(const Size &size) const noexcept
Map image contents to a given area.
Definition: Image.h:344
fsdk::Image::getScanLine
FSDK_API void * getScanLine(int y) noexcept
Get image scanline data.
fsdk::Image::Error
Error
Image error codes.
Definition: Image.h:77
fsdk::Image::saveToMemory
FSDK_API Result< Image::Error > saveToMemory(Image::Type type, IArchive *archive, const Format format) const noexcept
Convert and save image to memory buffer.
fsdk::Image::Error::InvalidType
@ InvalidType
Unsupported type.
fsdk::Image::m_ref
int * m_ref
reference counter. nullptr if image does not own data.
Definition: Image.h:898
fsdk::SubImage
Sub Image.
Definition: SubImage.h:11
fsdk::Image::Error::ReleasedInOtherThread
@ ReleasedInOtherThread
Failed to retain image: it was released in another thread.
fsdk::Image::getRefCount
FSDK_API int getRefCount() const noexcept
Obtain reference count.
fsdk::Image::TargetDevice
TargetDevice
Target device that fsdk::Image algorithms will be running on.
Definition: Image.h:55
fsdk::Image::Error::InvalidFormat
@ InvalidFormat
Unsupported format.
fsdk::Image::ImageCompression::IC_SMALL_COMPRESSION
@ IC_SMALL_COMPRESSION
compression with minimal (or without) quality loss (only for png or jpg image)
fsdk::Image::set
FSDK_API Result< Error > set(int width, int height, Format format, const void *data, MemoryResidence residence=MemoryResidence::MemoryCPU) noexcept
Initializes an image with provided data. If current image is not empty and it's size and format match...
fsdk::Image::Error::InvalidArchive
@ InvalidArchive
Archive error.
fsdk::Image::getScanLineAs
const T * getScanLineAs(int y) const noexcept
Get image scanline data.
Definition: Image.h:764
fsdk::Sizer
Helper entity to measure size of dynamic objects in memory.
Definition: Sizer.h:10
fsdk::Image::ImageCompression::IC_MEDIUM_COMPRESSION
@ IC_MEDIUM_COMPRESSION
medium compression (only for png or jpg)
fsdk::Image::Type
Type
Supported image types.
Definition: Image.h:43
fsdk::Image::Error::FailedToLoad
@ FailedToLoad
Error during image loading.
fsdk::Image::Error::InvalidWidth
@ InvalidWidth
Invalid width.