Face Engine SDK  5.25.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/RotationType.h>
8 #include <fsdk/Types/Sizer.h>
9 #include <fsdk/Types/SubImage.h>
10 
11 namespace fsdk {
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 
68  enum class ImageCompression {
75  };
79  enum class Error : uint32_t {
80  Ok,
81  InvalidWidth,
85  InvalidImage,
87  InvalidPath,
88  InvalidType,
96  FailedToSave,
97  FailedToLoad,
100  };
101 
107  enum class MemoryResidence : uint32_t {
108  MemoryCPU,
109  MemoryGPU,
110  MemoryNPU,
111  MemoryNPU_DPP,
112  };
113 
117 
128  FSDK_API Image(
129  int width,
130  int height,
131  Format format,
132  MemoryResidence residence = MemoryResidence::MemoryCPU,
133  int deviceId = 0) noexcept;
134 
147  FSDK_API Image(
148  int width,
149  int height,
150  Format format,
151  const void* data,
152  MemoryResidence residence = MemoryResidence::MemoryCPU,
153  int deviceId = 0) noexcept;
154 
172  FSDK_API Image(
173  int width,
174  int height,
175  Format format,
176  void* data,
177  bool copy,
178  MemoryResidence residence = MemoryResidence::MemoryCPU,
179  int deviceId = 0) noexcept;
180 
185  FSDK_API Image(const Image& other) noexcept;
186 
191  FSDK_API Image(Image&& other) noexcept;
192 
198  FSDK_API explicit Image(const SubImage& subImage) noexcept;
199 
200  FSDK_API ~Image();
201 
217  int width,
218  int height,
219  Format format,
220  bool cleanup = true,
221  MemoryResidence residence = MemoryResidence::MemoryCPU,
222  int deviceId = 0) noexcept;
223 
240  int width,
241  int height,
242  Format format,
243  const void* data,
244  MemoryResidence residence = MemoryResidence::MemoryCPU,
245  int deviceId = 0) noexcept;
246 
267  int width,
268  int height,
269  Format format,
270  void* data,
271  bool copy,
272  MemoryResidence residence = MemoryResidence::MemoryCPU,
273  int deviceId = 0) noexcept;
274 
285  create(const fsdk::Image& source, MemoryResidence residence, int deviceId = 0) noexcept;
286 
305  int width,
306  int height,
307  Format format,
308  const void* data,
309  MemoryResidence residence = MemoryResidence::MemoryCPU,
310  int deviceId = 0) noexcept;
311 
334  int width,
335  int height,
336  Format format,
337  void* data,
338  bool copy,
339  MemoryResidence residence = MemoryResidence::MemoryCPU,
340  int deviceId = 0) noexcept;
341 
347  FSDK_API Result<Error> set(const Image& other) noexcept;
348 
354  FSDK_API Result<Error> set(const SubImage& subImage) noexcept;
355 
368  FSDK_API SubImage map(int x, int y, int width, int height) const noexcept;
369 
377  SubImage map(const Rect& rect) const noexcept {
378  return map(rect.x, rect.y, rect.width, rect.height);
379  }
380 
390  SubImage map(const Size& size) const noexcept {
391  return map(Point2i(0, 0), size);
392  }
393 
402  SubImage map(const Point2i& origin, const Size& size) const noexcept {
403  return map(origin.x, origin.y, size.x, size.y);
404  }
405 
419  FSDK_API Image extract(int x, int y, int width, int height) const noexcept;
420 
429  Image extract(const Rect& rect) const noexcept {
430  return extract(rect.x, rect.y, rect.width, rect.height);
431  }
432 
443  Image extract(const Size& size) const noexcept {
444  return extract(Point2i(0, 0), size);
445  }
446 
456  Image extract(const Point2i& origin, const Size& size) const noexcept {
457  return extract(origin.x, origin.y, size.x, size.y);
458  }
459 
467  FSDK_API static Result<Error>
468  guessTypeFromMemory(const void* data, const uint32_t sizeInBytes, Type& type) noexcept;
469 
475  Image clone() const noexcept {
476  return {getWidth(), getHeight(), getFormat(), getData(), getMemoryResidence(), getDeviceId()};
477  }
478 
498  Image& dest,
499  int x,
500  int y,
501  int width,
502  int height,
503  Format format,
504  TargetDevice device = TargetDevice::CPU) const noexcept;
505 
521  Image& dest,
522  const Point2i& origin,
523  const Size& size,
524  Format format,
525  TargetDevice device = TargetDevice::CPU) const noexcept {
526  return convert(dest, origin.x, origin.y, size.x, size.y, format, device);
527  }
528 
545  convert(Image& dest, const Size& size, Format format, TargetDevice device = TargetDevice::CPU)
546  const noexcept {
547  return convert(dest, Point2i(0, 0), size, format, device);
548  }
549 
564  convert(Image& dest, const Rect& rect, Format format, TargetDevice device = TargetDevice::CPU)
565  const noexcept {
566  return convert(dest, rect.x, rect.y, rect.width, rect.height, format, device);
567  }
568 
579  Result<Image::Error>
580  convert(Image& dest, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
581  return convert(dest, getRect(), format, device);
582  }
583 
589  FSDK_API Image rescale(float scale) const noexcept;
590 
602  const char* path,
603  fsdk::Image::ImageCompression additionalFlag =
605 
616  FSDK_API Result<Error> save(const char* path, const Format format) const noexcept;
617 
629  Image::Type type,
630  IArchive* archive,
631  fsdk::Image::ImageCompression additionalFlag =
632  fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept;
633 
646  saveToMemory(Image::Type type, IArchive* archive, const Format format) const noexcept;
647 
660  FSDK_API Result<Error> load(const char* path) noexcept;
661 
671  FSDK_API Result<Error> load(const char* path, const Format format) noexcept;
672 
686  FSDK_API Result<Error> loadFromMemory(const void* data, const uint32_t sizeInBytes) noexcept;
687 
697  FSDK_API Result<Error> rotate(Image& dest, RotationType rotationType) const noexcept;
698 
711  loadFromMemory(const void* data, const uint32_t sizeInBytes, const Format format) noexcept;
712 
729  loadFromMemoryOfType(const void* data, const uint32_t sizeInBytes, const Type type) noexcept;
730 
743  const void* data,
744  const uint32_t sizeInBytes,
745  const Type type,
746  const Format format) noexcept;
747 
751  Image& operator=(const Image& other) noexcept {
752  set(other);
753 
754  return *this;
755  }
756 
761  if(this != &other) {
762  release();
763  swap(other);
764  }
765 
766  return *this;
767  }
768 
770  bool isNull() const noexcept {
771  return getData() == nullptr;
772  }
773 
777  bool isValid() const noexcept {
778  return !isNull() && getHeight() > 0 && getWidth() > 0 && 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>
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 static_cast<float>(getWidth()) / static_cast<float>(getHeight());
871  }
872 
875  return m_format;
876  }
877 
878  MemoryResidence getMemoryResidence() const noexcept {
879  return m_residence;
880  }
881 
882  int getDeviceId() const noexcept {
883  return m_deviceId;
884  }
885 
888  return Size(getWidth(), getHeight());
889  }
890 
895  return Rect(0, 0, getWidth(), getHeight());
896  }
897 
902  bool ownsData() const noexcept {
903  return !!m_ref;
904  }
905 
910  bool isSharedWith(const Image& other) const noexcept {
911  return getData() == other.getData();
912  }
913 
917  void swap(Image& other) noexcept {
918  std::swap(m_data, other.m_data);
919  std::swap(m_ref, other.m_ref);
920  std::swap(m_height, other.m_height);
921  std::swap(m_width, other.m_width);
922  std::swap(m_format, other.m_format);
923  std::swap(m_residence, other.m_residence);
924  }
925 
928  void reset() noexcept {
929  Image().swap(*this);
930  }
931 
937  bool equalWeak(const fsdk::Image& other) const noexcept {
938  return m_width == other.getWidth() && m_height == other.getHeight() && m_format == other.getFormat() &&
939  m_residence == other.getMemoryResidence();
940  }
941 
947  bool equalStrong(const fsdk::Image& other) const noexcept {
948  return equalWeak(other) && m_data == other.getData();
949  }
950 
951  FSDK_API void putPixel(uint32_t x, uint32_t y) noexcept;
952 
953  protected:
954  void* m_data;
955  int* m_ref;
956  int m_height;
957  int m_width;
960  MemoryResidence m_residence;
961 
966  FSDK_API static void* allocate(int size) noexcept;
967 
971  FSDK_API static void deallocate(void* memory) noexcept;
972 
976  FSDK_API int retain() noexcept;
977 
981  FSDK_API int release() noexcept;
982 
986  FSDK_API int getRefCount() const noexcept;
987  };
988 
993  const char* toString(Image::MemoryResidence residence);
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:
1008  return "Ok";
1010  return "Unsupported type";
1012  return "Invalid path";
1014  return "Error during image saving";
1016  return "Error during image loading";
1018  return "Invalid image";
1020  return "Invalid image width";
1022  return "Invalid image height";
1024  return "Unsupported format";
1026  return "Memory error";
1028  return "Bitmap error";
1030  return "Archive error";
1032  return "Bad input data pointer";
1034  return "Bad input data size";
1036  return "Required conversion not implemented";
1038  return "Selected Target Device is not supported for this system";
1040  return "Error during initialization";
1042  return "Failed to retain image: it was released in another thread.";
1043  default:
1044  return "Unknown error";
1045  }
1046  }
1047  };
1048 
1053  using ImageError = Image::Error;
1056 
1057 } // namespace fsdk
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:27
void reset() noexcept
Reset image contents.
Definition: Image.h:928
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:947
Vector2< int > Point2i
Definition: Vector2.h:294
Rect getRect() const noexcept
Definition: Image.h:894
Image in NPU PreProcessing module memory.
Type height
Rectangle height.
Definition: Rect.h:15
int m_height
image height.
Definition: Image.h:956
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:200
bool isValid() const noexcept
Definition: Format.h:253
Image format.
Definition: Format.h:11
bool isNull() const noexcept
Definition: Image.h:770
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
Result< Image::Error > const noexcept
Convert image format.
Definition: Image.h:546
Format getFormat() const noexcept
Definition: Image.h:874
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:8
Bitmap error occurred.
MemoryResidence
Memory residence.
Definition: Image.h:107
int getHeight() const noexcept
Definition: Image.h:864
Type width
Rectangle width.
Definition: Rect.h:14
Conversion not implemented.
Format m_format
image format (
Definition: Image.h:959
Common SDK definitions.
Invalid memory residence.
SubImage map(const Size &size) const noexcept
Map image contents to a given area.
Definition: Image.h:390
bool isSharedWith(const Image &other) const noexcept
Definition: Image.h:910
void * m_data
raw image data.
Definition: Image.h:954
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:955
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:958
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:456
static FSDK_API void * allocate(int size) noexcept
Allocate memory.
Type
Supported image types.
Definition: Image.h:43
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:937
void swap(Image &other) noexcept
Swap contents with another image.
Definition: Image.h:917
Error during image loading.
Failed to retain image: it was released in another thread.
int m_width
image width.
Definition: Image.h:957
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:38
T * getDataAs() noexcept
Definition: Image.h:842
FSDK_API int getDataSize() const noexcept
Target Device is not supported for this system.
FSDK_API int release() noexcept
Decrease reference count.
Image in Host device memory.
no compression (only for png or jpg image)
Archive interface.
Definition: IObject.h:38
SubImage map(const Point2i &origin, const Size &size) const noexcept
Map image contents to a given area.
Definition: Image.h:402
const char * toString(Image::MemoryResidence residence)
Returns a string representation of a MemoryResidence type.
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:443
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:79
bool ownsData() const noexcept
Definition: Image.h:902
Sub Image.
Definition: SubImage.h:13
Result< Image::Error > convert(Image &dest, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
Convert image format.
Definition: Image.h:580
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:475
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:429
Helper entity to measure size of dynamic objects in memory.
Definition: Sizer.h:9
FSDK_API int retain() noexcept
Increase reference count.
Vector2< int > Size
Definition: Vector2.h:303
Size getSize() const noexcept
Definition: Image.h:887
Image & operator=(Image &&other) noexcept
Move other image.
Definition: Image.h:760
Type y
Upper left corner y-coordinate.
Definition: Rect.h:13
int getWidth() const noexcept
Definition: Image.h:859
Image in NPU device memory.
Type x
Upper left corner x-coordinate.
Definition: Rect.h:12
bool isValid() const noexcept
Definition: Image.h:777
static FSDK_API Result< Error > guessTypeFromMemory(const void *data, const uint32_t sizeInBytes, Type &type) noexcept
Guess type of image written into memory.