Face Engine SDK  5.14.0
A face detection, recognition and tracking engine.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Image.h
1 #pragma once
2 
3 #include <fsdk/Def.h>
4 #include <fsdk/Types/Format.h>
5 #include <fsdk/Types/RotationType.h>
6 #include <fsdk/Types/Rect.h>
7 #include <fsdk/Types/Result.h>
8 #include <fsdk/Types/Sizer.h>
9 #include <fsdk/Types/SubImage.h>
10 
11 namespace fsdk
12 {
13 
14  struct IArchive;
15 
39  struct Image {
40 
44  enum class Type: uint8_t {
45  BMP,
46  JPG,
47  PNG,
48  PPM,
49  TIFF,
50  Unknown
51  };
52 
56  enum class TargetDevice {
57  CPU,
58  GPU,
59  NPU,
60  };
61 
68  enum class ImageCompression {
74  };
78  enum class Error: uint32_t {
79  Ok,
80  InvalidWidth,
84  InvalidImage,
86  InvalidPath,
87  InvalidType,
95  FailedToSave,
96  FailedToLoad,
99  };
100 
106  enum class MemoryResidence: uint32_t {
107  MemoryCPU,
108  MemoryGPU,
109  MemoryNPU,
110  MemoryNPU_DPP,
111  };
112 
115  FSDK_API Image() noexcept;
116 
127  FSDK_API Image(
128  int width,
129  int height,
130  Format format,
131  MemoryResidence residence = MemoryResidence::MemoryCPU,
132  int deviceId = 0) noexcept;
133 
146  FSDK_API Image(
147  int width,
148  int height,
149  Format format,
150  const void* data,
151  MemoryResidence residence = MemoryResidence::MemoryCPU,
152  int deviceId = 0) noexcept;
153 
171  FSDK_API Image(
172  int width,
173  int height,
174  Format format,
175  void* data,
176  bool copy,
177  MemoryResidence residence = MemoryResidence::MemoryCPU,
178  int deviceId = 0) noexcept;
179 
184  FSDK_API Image(const Image& other) noexcept;
185 
190  FSDK_API Image(Image&& other) noexcept;
191 
197  FSDK_API explicit Image(const SubImage& subImage) noexcept;
198 
199  FSDK_API ~Image();
200 
216  int width,
217  int height,
218  Format format,
219  bool cleanup = true,
220  MemoryResidence residence = MemoryResidence::MemoryCPU,
221  int deviceId = 0) noexcept;
222 
239  int width,
240  int height,
241  Format format,
242  const void* data,
243  MemoryResidence residence = MemoryResidence::MemoryCPU,
244  int deviceId = 0) noexcept;
245 
266  int width,
267  int height,
268  Format format,
269  void* data,
270  bool copy,
271  MemoryResidence residence = MemoryResidence::MemoryCPU,
272  int deviceId = 0) noexcept;
273 
283  FSDK_API Result<Error> create(const fsdk::Image& source, MemoryResidence residence, int deviceId = 0) noexcept;
284 
303  int width,
304  int height,
305  Format format,
306  const void* data,
307  MemoryResidence residence = MemoryResidence::MemoryCPU,
308  int deviceId = 0) noexcept;
309 
332  int width,
333  int height,
334  Format format,
335  void* data,
336  bool copy,
337  MemoryResidence residence = MemoryResidence::MemoryCPU,
338  int deviceId = 0) noexcept;
339 
345  FSDK_API Result<Error> set(const Image& other) noexcept;
346 
352  FSDK_API Result<Error> set(const SubImage& subImage) noexcept;
353 
366  FSDK_API SubImage map(int x, int y, int width, int height) const noexcept;
367 
375  SubImage map(const Rect& rect) const noexcept {
376  return map(rect.x, rect.y, rect.width, rect.height);
377  }
378 
388  SubImage map(const Size& size) const noexcept {
389  return map(Point2i(0, 0), size);
390  }
391 
400  SubImage map(const Point2i& origin, const Size& size) const noexcept {
401  return map(origin.x, origin.y, size.x, size.y);
402  }
403 
417  FSDK_API Image extract(int x, int y, int width, int height) const noexcept;
418 
427  Image extract(const Rect& rect) const noexcept {
428  return extract(rect.x, rect.y, rect.width, rect.height);
429  }
430 
441  Image extract(const Size& size) const noexcept {
442  return extract(Point2i(0, 0), size);
443  }
444 
454  Image extract(const Point2i& origin, const Size& size) const noexcept {
455  return extract(origin.x, origin.y, size.x, size.y);
456  }
457 
465  FSDK_API static Result<Error> guessTypeFromMemory(const void* data, const uint32_t sizeInBytes, Type& type) noexcept;
466 
472  Image clone() const noexcept {
473  return {
474  getWidth(),
475  getHeight(),
476  getFormat(),
477  getData(),
478  getMemoryResidence(),
479  getDeviceId()
480  };
481  }
482 
501  FSDK_API Result<Image::Error> convert(Image& dest, int x, int y, int width, int height, Format format, TargetDevice device = TargetDevice::CPU) const noexcept;
502 
517  Result<Image::Error> convert(Image& dest, const Point2i& origin, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
518  return convert(dest, origin.x, origin.y, size.x, size.y, format, device);
519  }
520 
536  Result<Image::Error> convert(Image& dest, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
537  return convert(dest, Point2i(0, 0), size, format, device);
538  }
539 
553  Result<Image::Error> convert(Image& dest, const Rect& rect, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
554  return convert(dest, rect.x, rect.y, rect.width, rect.height, format, device);
555  }
556 
567  Result<Image::Error> convert(Image& dest, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
568  return convert(dest, getRect(), format, device);
569  }
570 
576  FSDK_API Image rescale(float scale) const noexcept;
577 
588  FSDK_API Result <Image::Error> save(const char* path,
589  fsdk::Image::ImageCompression additionalFlag =
591 
603  const char* path,
604  const Format format) const noexcept;
605 
617  saveToMemory(Image::Type type,
618  IArchive* archive,
619  fsdk::Image::ImageCompression additionalFlag = fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept;
620 
633  Image::Type type,
634  IArchive* archive,
635  const Format format) const noexcept;
636 
649  FSDK_API Result<Error> load(const char* path) noexcept;
650 
661  const char* path,
662  const Format format) noexcept;
663 
678  const void* data,
679  const uint32_t sizeInBytes) noexcept;
680 
690  FSDK_API Result<Error> rotate(Image& dest, RotationType rotationType) const noexcept;
691 
704  const void* data,
705  const uint32_t sizeInBytes,
706  const Format format) noexcept;
707 
724  const void* data,
725  const uint32_t sizeInBytes,
726  const Type type) noexcept;
727 
740  const void* data,
741  const uint32_t sizeInBytes,
742  const Type type,
743  const Format format) noexcept;
744 
748  Image& operator = (const Image& other) noexcept {
749  set(other);
750 
751  return *this;
752  }
753 
757  Image& operator = (Image&& other) noexcept {
758  if(this != &other) {
759  release();
760  swap(other);
761  }
762 
763  return *this;
764  }
765 
767  bool isNull() const noexcept {
768  return getData() == nullptr;
769  }
770 
774  bool isValid() const noexcept {
775  return !isNull() &&
776  getHeight() > 0 &&
777  getWidth() > 0 &&
778  getFormat().isValid();
779  }
780 
784  operator bool () const noexcept {
785  return isValid();
786  }
787 
792  FSDK_API void* getScanLine(int y) noexcept;
793 
798  FSDK_API const void* getScanLine(int y) const noexcept;
799 
802  FSDK_API int getDataSize() const noexcept;
803 
807  FSDK_API void getDataSize(Sizer& sizer) const noexcept;
808 
813  template<typename T>
814  T* getScanLineAs(int y) noexcept {
815  return reinterpret_cast<T*>(getScanLine(y));
816  }
817 
822  template<typename T>
823  const T* getScanLineAs(int y) const noexcept {
824  return reinterpret_cast<const T*>(getScanLine(y));
825  }
826 
829  void* getData() noexcept {
830  return m_data;
831  }
832 
835  const void* getData() const noexcept {
836  return m_data;
837  }
838 
841  template<typename T>
842  T* getDataAs() noexcept {
843  return reinterpret_cast<T*>(getData());
844  }
845 
848  template<typename T>
849  const T* getDataAs() const noexcept {
850  return reinterpret_cast<const T*>(getData());
851  }
852 
854  int getRowSize() const noexcept {
855  return getFormat().computePitch(getWidth());
856  }
857 
859  int getWidth() const noexcept {
860  return m_width;
861  }
862 
864  int getHeight() const noexcept {
865  return m_height;
866  }
867 
869  float getAspectRatio() const noexcept {
870  return
871  static_cast<float>(getWidth()) /
872  static_cast<float>(getHeight());
873  }
874 
876  Format getFormat() const noexcept {
877  return m_format;
878  }
879 
880  MemoryResidence getMemoryResidence() const noexcept {
881  return m_residence;
882  }
883 
884  int getDeviceId() const noexcept {
885  return m_deviceId;
886  }
887 
889  Size getSize() const noexcept {
890  return Size(getWidth(), getHeight());
891  }
892 
896  Rect getRect() const noexcept {
897  return Rect(0, 0, getWidth(), getHeight());
898  }
899 
904  bool ownsData() const noexcept {
905  return !!m_ref;
906  }
907 
912  bool isSharedWith(const Image& other) const noexcept {
913  return getData() == other.getData();
914  }
915 
919  void swap(Image& other) noexcept {
920  std::swap(m_data, other.m_data);
921  std::swap(m_ref, other.m_ref);
922  std::swap(m_height, other.m_height);
923  std::swap(m_width, other.m_width);
924  std::swap(m_format, other.m_format);
925  std::swap(m_residence, other.m_residence);
926  }
927 
930  void reset() noexcept {
931  Image().swap(*this);
932  }
933 
939  bool equalWeak(const fsdk::Image& other) const noexcept {
940  return
941  m_width == other.getWidth() &&
942  m_height == other.getHeight() &&
943  m_format == other.getFormat() &&
944  m_residence == other.getMemoryResidence();
945  }
946 
952  bool equalStrong(const fsdk::Image& other) const noexcept {
953  return equalWeak(other) && m_data == other.getData();
954  }
955 
956 
957  FSDK_API void putPixel(uint32_t x, uint32_t y) noexcept;
958 
959  protected:
960  void* m_data;
961  int* m_ref;
962  int m_height;
963  int m_width;
966  MemoryResidence m_residence;
967 
972  FSDK_API static void* allocate(int size) noexcept;
973 
977  FSDK_API static void deallocate(void* memory) noexcept;
978 
982  FSDK_API int retain() noexcept;
983 
987  FSDK_API int release() noexcept;
988 
992  FSDK_API int getRefCount() const noexcept;
993  };
994 
998  template<>
1000 
1001  static bool isOk(Image::Error error) noexcept {
1002  return error == Image::Error::Ok;
1003  }
1004 
1005  static const char* toString (Image::Error error) noexcept {
1006  switch(error) {
1007  case Image::Error::Ok: return "Ok";
1008  case Image::Error::InvalidType: return "Unsupported type";
1009  case Image::Error::InvalidPath: return "Invalid path";
1010  case Image::Error::FailedToSave: return "Error during image saving";
1011  case Image::Error::FailedToLoad: return "Error during image loading";
1012  case Image::Error::InvalidImage: return "Invalid image";
1013  case Image::Error::InvalidWidth: return "Invalid image width";
1014  case Image::Error::InvalidHeight: return "Invalid image height";
1015  case Image::Error::InvalidFormat: return "Unsupported format";
1016  case Image::Error::InvalidMemory: return "Memory error";
1017  case Image::Error::InvalidBitmap: return "Bitmap error";
1018  case Image::Error::InvalidArchive: return "Archive error";
1019  case Image::Error::InvalidDataPtr: return "Bad input data pointer";
1020  case Image::Error::InvalidDataSize: return "Bad input data size";
1021  case Image::Error::InvalidConversion: return "Required conversion not implemented";
1022  case Image::Error::InvalidDevice: return "Selected Target Device is not supported for this system";
1023  case Image::Error::FailedToInitialize: return "Error during initialization";
1024  case Image::Error::ReleasedInOtherThread: return "Failed to retain image: it was released in another thread.";
1025  default: return "Unknown error";
1026  }
1027  }
1028  };
1029 
1034  using ImageError = Image::Error;
1037 
1038 }
Error at memory opening.
medium compression (only for png or jpg)
Error during apply cuda kernel.
#define FSDK_API
Dummy.
Definition: Def.h:27
FSDK_API Result< Error > loadFromMemory(const void *data, const uint32_t sizeInBytes) noexcept
Load image from memory.
float getAspectRatio() const noexcept
Definition: Image.h:869
A structure that encapsulates an action result enumeration.
Definition: Result.h:29
void reset() noexcept
Reset image contents.
Definition: Image.h:930
static FSDK_API void deallocate(void *memory) noexcept
Free memory.
bool equalStrong(const fsdk::Image &other) const noexcept
Performs strong comparison of this image with other. Beside weak comparison strong comparison also ch...
Definition: Image.h:952
Vector2< int > Point2i
Definition: Vector2.h:290
Rect getRect() const noexcept
Definition: Image.h:896
Image in NPU PreProcessing module memory.
Type height
Rectangle height.
Definition: Rect.h:16
int m_height
image height.
Definition: Image.h:962
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.
maximum compression level (only for png or jpg)
int computePitch(int rowWidth) const noexcept
Compute row size in bytes.
Definition: Format.h:140
bool isValid() const noexcept
Definition: Format.h:193
Image format.
Definition: Format.h:11
bool isNull() const noexcept
Definition: Image.h:767
Bad path for saving / loading.
FSDK_API Result< Error > load(const char *path) noexcept
Load image from file.
void * getData() noexcept
Definition: Image.h:829
Format getFormat() const noexcept
Definition: Image.h:876
const void * getData() const noexcept
Definition: Image.h:835
const T * getDataAs() const noexcept
Definition: Image.h:849
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_API Result< Error > set(int width, int height, Format format, const void *data, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
Initializes an image with provided data. If current image is not empty and it&#39;s size and format match...
int getRowSize() const noexcept
Definition: Image.h:854
T * getScanLineAs(int y) noexcept
Get image scanline data.
Definition: Image.h:814
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&#39;s own reference count.
RotationType
Image rotation type.
Definition: RotationType.h:10
FSDK_API Image rescale(float scale) const noexcept
Rescale image keeping proportions.
Definition: Result.h:9
Bitmap error occurred.
MemoryResidence
Memory residence.
Definition: Image.h:106
int getHeight() const noexcept
Definition: Image.h:864
Type width
Rectangle width.
Definition: Rect.h:15
Conversion not implemented.
Format m_format
image format (
Definition: Image.h:965
Common SDK definitions.
Invalid memory residence.
SubImage map(const Size &size) const noexcept
Map image contents to a given area.
Definition: Image.h:388
bool isSharedWith(const Image &other) const noexcept
Definition: Image.h:912
void * m_data
raw image data.
Definition: Image.h:960
Result< Image::Error > convert(Image &dest, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:536
FSDK_API Result< Error > create(int width, int height, Format format, bool cleanup=true, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
Initializes an empty image and preallocates storage buffer of given size.
int * m_ref
reference counter. nullptr if image does not own data.
Definition: Image.h:961
const T * getScanLineAs(int y) const noexcept
Get image scanline data.
Definition: Image.h:823
FSDK_API int getRefCount() const noexcept
Obtain reference count.
Error during image saving.
int m_deviceId
id of the device where image memory is allocated
Definition: Image.h:964
FSDK_API SubImage map(int x, int y, int width, int height) const noexcept
Map image contents to a given area.
Image extract(const Point2i &origin, const Size &size) const noexcept
Extract a sub image of this image. The new image will have it&#39;s own reference count.
Definition: Image.h:454
static FSDK_API void * allocate(int size) noexcept
Allocate memory.
Type
Supported image types.
Definition: Image.h:44
bool equalWeak(const fsdk::Image &other) const noexcept
Performs weak comparison of this image with other. Weak in this context means only image parameters s...
Definition: Image.h:939
void swap(Image &other) noexcept
Swap contents with another image.
Definition: Image.h:919
Error during image loading.
Failed to retain image: it was released in another thread.
int m_width
image width.
Definition: Image.h:963
Image in Cuda device memory.
ImageCompression
Supported compression type is used only for jpg and png types.
Definition: Image.h:68
Image.
Definition: Image.h:39
compression with minimal (or without) quality loss (only for png or jpg image)
T * getDataAs() noexcept
Definition: Image.h:842
FSDK_API int getDataSize() const noexcept
Target Device is not supported for this system.
Image & operator=(const Image &other) noexcept
Assign other image.
Definition: Image.h:748
FSDK_API int release() noexcept
Decrease reference count.
Image in Host device memory.
no compression (only for png or jpg image)
Result< Image::Error > convert(Image &dest, const Rect &rect, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:553
Archive interface.
Definition: IObject.h:37
SubImage map(const Point2i &origin, const Size &size) const noexcept
Map image contents to a given area.
Definition: Image.h:400
FSDK_API Result< Error > rotate(Image &dest, RotationType rotationType) const noexcept
Rotates an image on 90, 180 and 270 degrees. Allocates a new buffer of given size and fills image con...
Image extract(const Size &size) const noexcept
Extract a sub image of this image. The new image will have it&#39;s own reference count.
Definition: Image.h:441
Bad input data pointer.
FSDK_API Result< Error > loadFromMemoryOfType(const void *data, const uint32_t sizeInBytes, const Type type) noexcept
Load image from memory of specific type.
FSDK_API void * getScanLine(int y) noexcept
Get image scanline data.
Error
Image error codes.
Definition: Image.h:78
bool ownsData() const noexcept
Definition: Image.h:904
Sub Image.
Definition: SubImage.h:10
Result< Image::Error > convert(Image &dest, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:567
FSDK_API Image() noexcept
Initializes an empty image.
more than medium compression (only for png or jpg)
Error during initialization.
Image clone() const noexcept
Create a copy of this image. The new image will have it&#39;s own reference count.
Definition: Image.h:472
FSDK_API Result< Image::Error > save(const char *path, fsdk::Image::ImageCompression additionalFlag=fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept
Save image.
TargetDevice
Target device that fsdk::Image algorithms will be running on.
Definition: Image.h:56
Image extract(const Rect &rect) const noexcept
Extract a sub image of this image. The new image will have it&#39;s own reference count.
Definition: Image.h:427
Helper entity to measure size of dynamic objects in memory.
Definition: Sizer.h:10
FSDK_API int retain() noexcept
Increase reference count.
Vector2< int > Size
Definition: Vector2.h:299
Size getSize() const noexcept
Definition: Image.h:889
Type y
Upper left corner y-coordinate.
Definition: Rect.h:14
int getWidth() const noexcept
Definition: Image.h:859
Image in NPU device memory.
Type x
Upper left corner x-coordinate.
Definition: Rect.h:13
bool isValid() const noexcept
Definition: Image.h:774
static FSDK_API Result< Error > guessTypeFromMemory(const void *data, const uint32_t sizeInBytes, Type &type) noexcept
Guess type of image written into memory.