Face Engine SDK  5.8.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/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 
125  FSDK_API Image(
126  int width,
127  int height,
128  Format format,
129  MemoryResidence residence = MemoryResidence::MemoryCPU,
130  int deviceId = 0) noexcept;
131 
144  FSDK_API Image(
145  int width,
146  int height,
147  Format format,
148  const void* data,
149  MemoryResidence residence = MemoryResidence::MemoryCPU,
150  int deviceId = 0) noexcept;
151 
169  FSDK_API Image(
170  int width,
171  int height,
172  Format format,
173  void* data,
174  bool copy,
175  MemoryResidence residence = MemoryResidence::MemoryCPU,
176  int deviceId = 0) noexcept;
177 
182  FSDK_API Image(const Image& other) noexcept;
183 
188  FSDK_API Image(Image&& other) noexcept;
189 
195  FSDK_API explicit Image(const SubImage& subImage) noexcept;
196 
197  FSDK_API ~Image();
198 
214  int width,
215  int height,
216  Format format,
217  bool cleanup = true,
218  MemoryResidence residence = MemoryResidence::MemoryCPU,
219  int deviceId = 0) noexcept;
220 
237  int width,
238  int height,
239  Format format,
240  const void* data,
241  MemoryResidence residence = MemoryResidence::MemoryCPU,
242  int deviceId = 0) noexcept;
243 
264  int width,
265  int height,
266  Format format,
267  void* data,
268  bool copy,
269  MemoryResidence residence = MemoryResidence::MemoryCPU,
270  int deviceId = 0) noexcept;
271 
281  FSDK_API Result<Error> create(const fsdk::Image& source, MemoryResidence residence, int deviceId = 0) noexcept;
282 
301  int width,
302  int height,
303  Format format,
304  const void* data,
305  MemoryResidence residence = MemoryResidence::MemoryCPU,
306  int deviceId = 0) noexcept;
307 
330  int width,
331  int height,
332  Format format,
333  void* data,
334  bool copy,
335  MemoryResidence residence = MemoryResidence::MemoryCPU,
336  int deviceId = 0) noexcept;
337 
343  FSDK_API Result<Error> set(const Image& other) noexcept;
344 
350  FSDK_API Result<Error> set(const SubImage& subImage) noexcept;
351 
364  FSDK_API SubImage map(int x, int y, int width, int height) const noexcept;
365 
373  SubImage map(const Rect& rect) const noexcept {
374  return map(rect.x, rect.y, rect.width, rect.height);
375  }
376 
386  SubImage map(const Size& size) const noexcept {
387  return map(Point2i(0, 0), size);
388  }
389 
398  SubImage map(const Point2i& origin, const Size& size) const noexcept {
399  return map(origin.x, origin.y, size.x, size.y);
400  }
401 
415  FSDK_API Image extract(int x, int y, int width, int height) const noexcept;
416 
425  Image extract(const Rect& rect) const noexcept {
426  return extract(rect.x, rect.y, rect.width, rect.height);
427  }
428 
439  Image extract(const Size& size) const noexcept {
440  return extract(Point2i(0, 0), size);
441  }
442 
452  Image extract(const Point2i& origin, const Size& size) const noexcept {
453  return extract(origin.x, origin.y, size.x, size.y);
454  }
455 
463  FSDK_API static Result<Error> guessTypeFromMemory(const void* data, const uint32_t sizeInBytes, Type& type) noexcept;
464 
470  Image clone() const noexcept {
471  return Image(
472  getWidth(),
473  getHeight(),
474  getFormat(),
475  getData());
476  }
477 
496  FSDK_API Result<Image::Error> convert(Image& dest, int x, int y, int width, int height, Format format, TargetDevice device = TargetDevice::CPU) const noexcept;
497 
512  Result<Image::Error> convert(Image& dest, const Point2i& origin, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
513  return convert(dest, origin.x, origin.y, size.x, size.y, format, device);
514  }
515 
531  Result<Image::Error> convert(Image& dest, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
532  return convert(dest, Point2i(0, 0), size, format, device);
533  }
534 
548  Result<Image::Error> convert(Image& dest, const Rect& rect, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
549  return convert(dest, rect.x, rect.y, rect.width, rect.height, format, device);
550  }
551 
562  Result<Image::Error> convert(Image& dest, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
563  return convert(dest, getRect(), format, device);
564  }
565 
571  FSDK_API Image rescale(float scale) const noexcept;
572 
583  FSDK_API Result <Image::Error> save(const char* path,
584  fsdk::Image::ImageCompression additionalFlag =
586 
598  const char* path,
599  const Format format) const noexcept;
600 
612  saveToMemory(Image::Type type,
613  IArchive* archive,
614  fsdk::Image::ImageCompression additionalFlag = fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept;
615 
628  Image::Type type,
629  IArchive* archive,
630  const Format format) const noexcept;
631 
644  FSDK_API Result<Error> load(const char* path) noexcept;
645 
656  const char* path,
657  const Format format) noexcept;
658 
673  const void* data,
674  const uint32_t sizeInBytes) noexcept;
675 
687  const void* data,
688  const uint32_t sizeInBytes,
689  const Format format) noexcept;
690 
707  const void* data,
708  const uint32_t sizeInBytes,
709  const Type type) noexcept;
710 
723  const void* data,
724  const uint32_t sizeInBytes,
725  const Type type,
726  const Format format) noexcept;
727 
731  Image& operator = (const Image& other) noexcept {
732  set(other);
733 
734  return *this;
735  }
736 
740  Image& operator = (Image&& other) noexcept {
741  if(this != &other) {
742  release();
743  swap(other);
744  }
745 
746  return *this;
747  }
748 
750  bool isNull() const noexcept {
751  return getData() == nullptr;
752  }
753 
757  bool isValid() const noexcept {
758  return !isNull() &&
759  getHeight() > 0 &&
760  getWidth() > 0 &&
761  getFormat().isValid();
762  }
763 
767  operator bool () const noexcept {
768  return isValid();
769  }
770 
775  FSDK_API void* getScanLine(int y) noexcept;
776 
781  FSDK_API const void* getScanLine(int y) const noexcept;
782 
785  FSDK_API int getDataSize() const noexcept;
786 
790  FSDK_API void getDataSize(Sizer& sizer) const noexcept;
791 
796  template<typename T>
797  T* getScanLineAs(int y) noexcept {
798  return reinterpret_cast<T*>(getScanLine(y));
799  }
800 
805  template<typename T>
806  const T* getScanLineAs(int y) const noexcept {
807  return reinterpret_cast<const T*>(getScanLine(y));
808  }
809 
812  void* getData() noexcept {
813  return m_data;
814  }
815 
818  const void* getData() const noexcept {
819  return m_data;
820  }
821 
824  template<typename T>
825  T* getDataAs() noexcept {
826  return reinterpret_cast<T*>(getData());
827  }
828 
831  template<typename T>
832  const T* getDataAs() const noexcept {
833  return reinterpret_cast<const T*>(getData());
834  }
835 
837  int getRowSize() const noexcept {
838  return getFormat().computePitch(getWidth());
839  }
840 
842  int getWidth() const noexcept {
843  return m_width;
844  }
845 
847  int getHeight() const noexcept {
848  return m_height;
849  }
850 
852  float getAspectRatio() const noexcept {
853  return
854  static_cast<float>(getWidth()) /
855  static_cast<float>(getHeight());
856  }
857 
859  Format getFormat() const noexcept {
860  return m_format;
861  }
862 
863  MemoryResidence getMemoryResidence() const noexcept {
864  return m_residence;
865  }
866 
867  int getDeviceId() const noexcept {
868  return m_deviceId;
869  }
870 
872  Size getSize() const noexcept {
873  return Size(getWidth(), getHeight());
874  }
875 
879  Rect getRect() const noexcept {
880  return Rect(0, 0, getWidth(), getHeight());
881  }
882 
887  bool ownsData() const noexcept {
888  return !!m_ref;
889  }
890 
895  bool isSharedWith(const Image& other) const noexcept {
896  return getData() == other.getData();
897  }
898 
902  void swap(Image& other) noexcept {
903  std::swap(m_data, other.m_data);
904  std::swap(m_ref, other.m_ref);
905  std::swap(m_height, other.m_height);
906  std::swap(m_width, other.m_width);
907  std::swap(m_format, other.m_format);
908  std::swap(m_residence, other.m_residence);
909  }
910 
913  void reset() noexcept {
914  Image().swap(*this);
915  }
916 
922  bool equalWeak(const fsdk::Image& other) noexcept {
923  return
924  m_width == other.getWidth() &&
925  m_height == other.getHeight() &&
926  m_format == other.getFormat() &&
927  m_residence == other.getMemoryResidence();
928  }
929 
935  bool equalStrong(const fsdk::Image& other) noexcept {
936  return equalWeak(other) && m_data == other.getData();
937  }
938 
939 
940  FSDK_API void putPixel(uint32_t x, uint32_t y) noexcept;
941 
942  protected:
943  void* m_data;
944  int* m_ref;
945  int m_height;
946  int m_width;
949  MemoryResidence m_residence;
950 
955  FSDK_API static void* allocate(int size) noexcept;
956 
960  FSDK_API static void deallocate(void* memory) noexcept;
961 
965  FSDK_API int retain() noexcept;
966 
970  FSDK_API int release() noexcept;
971 
975  FSDK_API int getRefCount() const noexcept;
976  };
977 
981  template<>
983 
984  static bool isOk(Image::Error error) noexcept {
985  return error == Image::Error::Ok;
986  }
987 
988  static const char* toString (Image::Error error) noexcept {
989  switch(error) {
990  case Image::Error::Ok: return "Ok";
991  case Image::Error::InvalidType: return "Unsupported type";
992  case Image::Error::InvalidPath: return "Invalid path";
993  case Image::Error::FailedToSave: return "Error during image saving";
994  case Image::Error::FailedToLoad: return "Error during image loading";
995  case Image::Error::InvalidImage: return "Invalid image";
996  case Image::Error::InvalidWidth: return "Invalid image width";
997  case Image::Error::InvalidHeight: return "Invalid image height";
998  case Image::Error::InvalidFormat: return "Unsupported format";
999  case Image::Error::InvalidMemory: return "Memory error";
1000  case Image::Error::InvalidBitmap: return "Bitmap error";
1001  case Image::Error::InvalidArchive: return "Archive error";
1002  case Image::Error::InvalidDataPtr: return "Bad input data pointer";
1003  case Image::Error::InvalidDataSize: return "Bad input data size";
1004  case Image::Error::InvalidConversion: return "Required conversion not implemented";
1005  case Image::Error::InvalidDevice: return "Selected Target Device is not supported for this system";
1006  case Image::Error::FailedToInitialize: return "Error during initialization";
1007  case Image::Error::ReleasedInOtherThread: return "Failed to retain image: it was released in another thread.";
1008  default: return "Unknown error";
1009  }
1010  }
1011  };
1012 
1017  using ImageError = Image::Error;
1020 
1021 }
Error at memory opening.
medium compression (only for png or jpg)
#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:852
A structure that encapsulates an action result enumeration.
Definition: Result.h:29
void reset() noexcept
Reset image contents.
Definition: Image.h:913
static FSDK_API void deallocate(void *memory) noexcept
Free memory.
Vector2< int > Point2i
Definition: Vector2.h:290
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:922
Rect getRect() const noexcept
Definition: Image.h:879
Image in NPU PreProcessing module memory.
Type height
Rectangle height.
Definition: Rect.h:16
int m_height
image height.
Definition: Image.h:945
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:121
bool isValid() const noexcept
Definition: Format.h:174
Image format.
Definition: Format.h:11
bool isNull() const noexcept
Definition: Image.h:750
Bad path for saving / loading.
FSDK_API Result< Error > load(const char *path) noexcept
Load image from file.
void * getData() noexcept
Definition: Image.h:812
Format getFormat() const noexcept
Definition: Image.h:859
const void * getData() const noexcept
Definition: Image.h:818
const T * getDataAs() const noexcept
Definition: Image.h:832
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:837
T * getScanLineAs(int y) noexcept
Get image scanline data.
Definition: Image.h:797
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.
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:104
int getHeight() const noexcept
Definition: Image.h:847
Type width
Rectangle width.
Definition: Rect.h:15
Conversion not implemented.
Format m_format
image format (
Definition: Image.h:948
Common SDK definitions.
Invalid memory residence.
SubImage map(const Size &size) const noexcept
Map image contents to a given area.
Definition: Image.h:386
bool isSharedWith(const Image &other) const noexcept
Definition: Image.h:895
void * m_data
raw image data.
Definition: Image.h:943
Result< Image::Error > convert(Image &dest, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:531
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:944
const T * getScanLineAs(int y) const noexcept
Get image scanline data.
Definition: Image.h:806
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:947
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:452
static FSDK_API void * allocate(int size) noexcept
Allocate memory.
Type
Supported image types.
Definition: Image.h:43
void swap(Image &other) noexcept
Swap contents with another image.
Definition: Image.h:902
Error during image loading.
Failed to retain image: it was released in another thread.
int m_width
image width.
Definition: Image.h:946
Image in Cuda device memory.
ImageCompression
Supported compression type is used only for jpg and png types.
Definition: Image.h:67
Image.
Definition: Image.h:38
compression with minimal (or without) quality loss (only for png or jpg image)
T * getDataAs() noexcept
Definition: Image.h:825
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:731
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:548
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:398
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:439
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:77
bool ownsData() const noexcept
Definition: Image.h:887
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:562
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:470
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:55
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:425
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:872
Type y
Upper left corner y-coordinate.
Definition: Rect.h:14
int getWidth() const noexcept
Definition: Image.h:842
Image in NPU device memory.
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:935
Type x
Upper left corner x-coordinate.
Definition: Rect.h:13
bool isValid() const noexcept
Definition: Image.h:757
static FSDK_API Result< Error > guessTypeFromMemory(const void *data, const uint32_t sizeInBytes, Type &type) noexcept
Guess type of image written into memory.