Face Engine SDK  5.4.1
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 
321  FSDK_API SubImage map(int x, int y, int width, int height) const noexcept;
322 
329  SubImage map(const Rect& rect) const noexcept {
330  return map(rect.x, rect.y, rect.width, rect.height);
331  }
332 
341  SubImage map(const Size& size) const noexcept {
342  return map(Point2i(0, 0), size);
343  }
344 
352  SubImage map(const Point2i& origin, const Size& size) const noexcept {
353  return map(origin.x, origin.y, size.x, size.y);
354  }
355 
368  FSDK_API Image extract(int x, int y, int width, int height) const noexcept;
369 
377  Image extract(const Rect& rect) const noexcept {
378  return extract(rect.x, rect.y, rect.width, rect.height);
379  }
380 
390  Image extract(const Size& size) const noexcept {
391  return extract(Point2i(0, 0), size);
392  }
393 
402  Image extract(const Point2i& origin, const Size& size) const noexcept {
403  return extract(origin.x, origin.y, size.x, size.y);
404  }
405 
413  FSDK_API static Result<Error> guessTypeFromMemory(const void* data, const uint32_t sizeInBytes, Type& type) noexcept;
414 
420  Image clone() const noexcept {
421  return Image(
422  getWidth(),
423  getHeight(),
424  getFormat(),
425  getData());
426  }
427 
446  FSDK_API Result<Image::Error> convert(Image& dest, int x, int y, int width, int height, Format format, TargetDevice device = TargetDevice::CPU) const noexcept;
447 
462  Result<Image::Error> convert(Image& dest, const Point2i& origin, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
463  return convert(dest, origin.x, origin.y, size.x, size.y, format, device);
464  }
465 
481  Result<Image::Error> convert(Image& dest, const Size& size, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
482  return convert(dest, Point2i(0, 0), size, format, device);
483  }
484 
498  Result<Image::Error> convert(Image& dest, const Rect& rect, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
499  return convert(dest, rect.x, rect.y, rect.width, rect.height, format, device);
500  }
501 
512  Result<Image::Error> convert(Image& dest, Format format, TargetDevice device = TargetDevice::CPU) const noexcept {
513  return convert(dest, getRect(), format, device);
514  }
515 
521  FSDK_API Image rescale(float scale) const noexcept;
522 
533  fsdk::Image::ImageCompression additionalFlag =
535 
546  const char* path,
547  const Format format) const noexcept;
548 
560  IArchive* archive,
562 
574  Image::Type type,
575  IArchive* archive,
576  const Format format) const noexcept;
577 
589  FSDK_API Result<Error> load(const char* path) noexcept;
590 
600  const char* path,
601  const Format format) noexcept;
602 
616  const void* data,
617  const uint32_t sizeInBytes) noexcept;
618 
629  const void* data,
630  const uint32_t sizeInBytes,
631  const Format format) noexcept;
632 
648  const void* data,
649  const uint32_t sizeInBytes,
650  const Type type) noexcept;
651 
663  const void* data,
664  const uint32_t sizeInBytes,
665  const Type type,
666  const Format format) noexcept;
667 
671  Image& operator = (const Image& other) noexcept {
672  set(other);
673 
674  return *this;
675  }
676 
680  Image& operator = (Image&& other) noexcept {
681  if(this != &other) {
682  release();
683  swap(other);
684  }
685 
686  return *this;
687  }
688 
690  bool isNull() const noexcept {
691  return getData() == nullptr;
692  }
693 
697  bool isValid() const noexcept {
698  return !isNull() &&
699  getHeight() > 0 &&
700  getWidth() > 0 &&
701  getFormat().isValid();
702  }
703 
707  operator bool () const noexcept {
708  return isValid();
709  }
710 
715  FSDK_API void* getScanLine(int y) noexcept;
716 
721  FSDK_API const void* getScanLine(int y) const noexcept;
722 
725  FSDK_API int getDataSize() const noexcept;
726 
730  FSDK_API void getDataSize(Sizer& sizer) const noexcept;
731 
736  template<typename T>
737  T* getScanLineAs(int y) noexcept {
738  return reinterpret_cast<T*>(getScanLine(y));
739  }
740 
745  template<typename T>
746  const T* getScanLineAs(int y) const noexcept {
747  return reinterpret_cast<const T*>(getScanLine(y));
748  }
749 
752  void* getData() noexcept {
753  return m_data;
754  }
755 
758  const void* getData() const noexcept {
759  return m_data;
760  }
761 
764  template<typename T>
765  T* getDataAs() noexcept {
766  return reinterpret_cast<T*>(getData());
767  }
768 
771  template<typename T>
772  const T* getDataAs() const noexcept {
773  return reinterpret_cast<const T*>(getData());
774  }
775 
777  int getRowSize() const noexcept {
778  return getFormat().computePitch(getWidth());
779  }
780 
782  int getWidth() const noexcept {
783  return m_width;
784  }
785 
787  int getHeight() const noexcept {
788  return m_height;
789  }
790 
792  float getAspectRatio() const noexcept {
793  return
794  static_cast<float>(getWidth()) /
795  static_cast<float>(getHeight());
796  }
797 
799  Format getFormat() const noexcept {
800  return m_format;
801  }
802 
803  MemoryResidence getMemoryResidence() const noexcept {
804  return m_residence;
805  }
806 
808  Size getSize() const noexcept {
809  return Size(getWidth(), getHeight());
810  }
811 
815  Rect getRect() const noexcept {
816  return Rect(0, 0, getWidth(), getHeight());
817  }
818 
823  bool ownsData() const noexcept {
824  return !!m_ref;
825  }
826 
831  bool isSharedWith(const Image& other) const noexcept {
832  return getData() == other.getData();
833  }
834 
838  void swap(Image& other) noexcept {
839  std::swap(m_data, other.m_data);
840  std::swap(m_ref, other.m_ref);
841  std::swap(m_height, other.m_height);
842  std::swap(m_width, other.m_width);
843  std::swap(m_format, other.m_format);
844  std::swap(m_residence, other.m_residence);
845  }
846 
849  void reset() noexcept {
850  Image().swap(*this);
851  }
852 
858  bool equalWeak(const fsdk::Image& other) noexcept {
859  return
860  m_width == other.getWidth() &&
861  m_height == other.getHeight() &&
862  m_format == other.getFormat() &&
863  m_residence == other.getMemoryResidence();
864  }
865 
871  bool equalStrong(const fsdk::Image& other) noexcept {
872  return equalWeak(other) && m_data == other.getData();
873  }
874 
875 
876  FSDK_API void putPixel(uint32_t x, uint32_t y) noexcept;
877 
878  protected:
879  void* m_data;
880  int* m_ref;
881  int m_height;
882  int m_width;
883 
885  MemoryResidence m_residence;
886 
891  FSDK_API static void* allocate(int size) noexcept;
892 
896  FSDK_API static void deallocate(void* memory) noexcept;
897 
901  FSDK_API int retain() noexcept;
902 
906  FSDK_API int release() noexcept;
907 
911  FSDK_API int getRefCount() const noexcept;
912  };
913 
917  template<>
919 
920  static bool isOk(Image::Error error) noexcept {
921  return error == Image::Error::Ok;
922  }
923 
924  static const char* toString (Image::Error error) noexcept {
925  switch(error) {
926  case Image::Error::Ok: return "Ok";
927  case Image::Error::InvalidType: return "Unsupported type";
928  case Image::Error::InvalidPath: return "Invalid path";
929  case Image::Error::FailedToSave: return "Error during image saving";
930  case Image::Error::FailedToLoad: return "Error during image loading";
931  case Image::Error::InvalidImage: return "Invalid image";
932  case Image::Error::InvalidWidth: return "Invalid image width";
933  case Image::Error::InvalidHeight: return "Invalid image height";
934  case Image::Error::InvalidFormat: return "Unsupported format";
935  case Image::Error::InvalidMemory: return "Memory error";
936  case Image::Error::InvalidBitmap: return "Bitmap error";
937  case Image::Error::InvalidArchive: return "Archive error";
938  case Image::Error::InvalidDataPtr: return "Bad input data pointer";
939  case Image::Error::InvalidDataSize: return "Bad input data size";
940  case Image::Error::InvalidConversion: return "Required conversion not implemented";
941  case Image::Error::InvalidDevice: return "Selected Target Device is not supported for this system";
942  case Image::Error::FailedToInitialize: return "Error during initialization";
943  case Image::Error::ReleasedInOtherThread: return "Failed to retain image: it was released in another thread.";
944  default: return "Unknown error";
945  }
946  }
947  };
948 
953  using ImageError = Image::Error;
956 
957 }
fsdk::Image::ownsData
bool ownsData() const noexcept
Definition: Image.h:823
fsdk::Image::m_width
int m_width
image width.
Definition: Image.h:882
fsdk::Image::m_height
int m_height
image height.
Definition: Image.h:881
fsdk::Image::getData
const void * getData() const noexcept
Definition: Image.h:758
fsdk::Image::getData
void * getData() noexcept
Definition: Image.h:752
fsdk::Image::MemoryResidence
MemoryResidence
Memory residence.
Definition: Image.h:104
fsdk::Image::getSize
Size getSize() const noexcept
Definition: Image.h:808
fsdk::Image::m_format
Format m_format
image format (
Definition: Image.h:884
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:498
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:481
fsdk::Image::Error::FailedToInitialize
@ FailedToInitialize
Error during initialization.
fsdk::Vector2< int >
fsdk::Image::getHeight
int getHeight() const noexcept
Definition: Image.h:787
fsdk::Image::swap
void swap(Image &other) noexcept
Swap contents with another image.
Definition: Image.h:838
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:512
fsdk::Image::Error::InvalidMemory
@ InvalidMemory
Error at memory opening.
fsdk::Image::getDataAs
const T * getDataAs() const noexcept
Definition: Image.h:772
fsdk::Image::isNull
bool isNull() const noexcept
Definition: Image.h:690
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:737
fsdk::Image::operator=
Image & operator=(const Image &other) noexcept
Assign an other image.
Definition: Image.h:671
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:377
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:879
fsdk::Image::Error::InvalidDataSize
@ InvalidDataSize
Bad input data size.
fsdk::Image::getDataAs
T * getDataAs() noexcept
Definition: Image.h:765
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:420
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:871
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:858
fsdk::Image::isSharedWith
bool isSharedWith(const Image &other) const noexcept
Definition: Image.h:831
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:390
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:777
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:301
fsdk::Image::getWidth
int getWidth() const noexcept
Definition: Image.h:782
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:849
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:462
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:352
fsdk::IArchive
Archive interface.
Definition: IObject.h:37
fsdk::Point2i
Vector2< int > Point2i
Definition: Vector2.h:292
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:402
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:792
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:815
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:799
fsdk::Image::isValid
bool isValid() const noexcept
Definition: Image.h:697
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:341
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:880
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:746
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.