205 lines
7.7 KiB
C++
205 lines
7.7 KiB
C++
/**
|
|
* @file IWarper.h
|
|
* @brief Image and landmarks warping
|
|
* @copyright VisionLabs LLC
|
|
* @date 04.10.2017
|
|
* */
|
|
|
|
#pragma once
|
|
|
|
#include "IDescriptor.h"
|
|
#include <fsdk/Types/Span.h>
|
|
|
|
#include <fsdk/vlc/future.h>
|
|
|
|
namespace fsdk {
|
|
struct EyesEstimation;
|
|
struct GazeEstimation;
|
|
}
|
|
|
|
namespace fsdk {
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
DECLARE_SMARTPTR(IWarper);
|
|
#endif
|
|
|
|
/**
|
|
* @brief Transformation data structure, used for warping.
|
|
* @details Use this structure to perform image and landmarks transformations.
|
|
* @note In no circumstances should you create OR edit this structure by yourself
|
|
* */
|
|
struct Transformation {
|
|
Vector2<float> centerP = {0, 0}; //From 0, scaled
|
|
float angleDeg = 0;
|
|
float scale = 0;
|
|
Vector2<int> detectionTopLeft = {0, 0}; //From 0, original size
|
|
|
|
bool isValid = false;
|
|
};
|
|
|
|
/**
|
|
* @brief Face detection area warper interface.
|
|
* @details Perform affine transformations on an image to properly align depicted face for descriptor extraction.
|
|
* */
|
|
struct IWarper : IRefCounted {
|
|
/**
|
|
* @brief Create transformation data struct.
|
|
* @param [in] detection detection coordinates in image space.
|
|
* @param [in] landmarks vector of landmarks to calculate warping angles.
|
|
* @return Transformation object.
|
|
* @see Transformation, Detection and Landmarks5 for details.
|
|
* */
|
|
virtual Transformation
|
|
createTransformation(
|
|
const Detection& detection,
|
|
const Landmarks5& landmarks) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Warp image.
|
|
* @param [in] image source image.
|
|
* @param [in] transformation transformation data.
|
|
* @param [out] transformedImage output transformed image.
|
|
* @return Result with error code.
|
|
* @see Transformation, Image, Result and FSDKError for details.
|
|
* @note image format must be R8G8B8, @see Format.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
warp(
|
|
const Image& image,
|
|
const Transformation& transformation,
|
|
Image& transformedImage) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Warp faces on multiple images.
|
|
* @param [in] images span of source images.
|
|
* @param [in] transformations span of transformation structures.
|
|
* @param [in/out] transformedImages span of output warped images.
|
|
* @note: all input images must have the same memory residence.
|
|
* @note: Each entry index in transformations span corresponds to the same index in images span
|
|
* to make warps from(i.e. transformations[i] <--> images[i]), so if there are multiple warps on
|
|
* the same image then this image must be duplicated in images span in order for the first statement
|
|
* to hold true.
|
|
* @note: if images in transformedImages span has the same parameters as the standard
|
|
* warped image has then no memory will be allocated and output data will be just copied
|
|
* to the backing memory of the output images. New images will be allocated otherwise.
|
|
* @return Result with error code.
|
|
* @see Span, Transformation, Image, Result and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
warp(
|
|
Span<const Image> images,
|
|
Span<const Transformation> transformations,
|
|
Span<Image> transformedImages) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Warp landmarks of size 5.
|
|
* @param [in] landmarks landmarks array of size 5
|
|
* @param [in] transformation transformation data.
|
|
* @param [out] transformedLandmarks output transformed landmarks.
|
|
* If transformation is created with detection, it's in the coordinates of transformed warped image,
|
|
* otherwise in the coordinates of detection.
|
|
* @return Result with error code.
|
|
* @see Transformation, Landmarks5, Result and FSDKError for details.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
warp(
|
|
const Landmarks5& landmarks,
|
|
const Transformation& transformation,
|
|
Landmarks5& transformedLandmarks) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Warp landmarks of size 68.
|
|
* @param [in] landmarks68 landmarks to warp.
|
|
* @param [in] transformation transformation data.
|
|
* @param [out] transformedLandmarks68 output transformed landmarks of size 68.
|
|
* If transformation is created with detection, it's in the coordinates of transformed warped image,
|
|
* otherwise in the coordinates of detection.
|
|
* @return Result with error code.
|
|
* @see Transformation, Landmarks68, Result and FSDKError for details.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
warp(
|
|
const Landmarks68& landmarks68,
|
|
const Transformation& transformation,
|
|
Landmarks68& transformedLandmarks68) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Warp irisLandmarks in EyesEstimation struct for both eyes.
|
|
* @details Warps from warped image coord. space to source image coordinates space,
|
|
* the one that was used to create transformation.
|
|
* @param [in] eyesEstimationInWarpCoordinates EyesEstimation straight out of EyeEstimator.
|
|
* Should be create from warpedImage, that was created with the same transformation object as the one passed.
|
|
* @param [in] transformation transformation data.
|
|
* @param [out] eyesEstimation eyes estimation with iris landmarks warped to source image coordinates space.
|
|
* @return Result with error code.
|
|
* @see Transformation, EyesEstimation, Result and FSDKError for details.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
unwarp(
|
|
const EyesEstimation& eyesEstimationInWarpCoordinates,
|
|
const Transformation& transformation,
|
|
EyesEstimation& eyesEstimation) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Warp landmarks of size 5 back to source image coordinates.
|
|
* @param [in] warpedLandmarks5 warped landmarks array of size 5.
|
|
* @param [in] transformation transformation data.
|
|
* @param [out] landmarks5 landmarks of size 5 warped back to source image coordinates.
|
|
* @return Result with error code.
|
|
* @see Transformation, Landmarks5, Result and FSDKError for details.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
unwarp(
|
|
const Landmarks5& warpedLandmarks5,
|
|
const Transformation& transformation,
|
|
Landmarks5& landmarks5) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Warp landmarks of size 68 back to source image coordinates.
|
|
* @param [in] warpedLandmarks5 warped landmarks array of size 68.
|
|
* @param [in] transformation transformation data.
|
|
* @param [out] landmarks5 landmarks of size 68 warped back to source image coordinates.
|
|
* @return Result with error code.
|
|
* @see Transformation, Landmarks68, Result and FSDKError for details.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
unwarp(
|
|
const Landmarks68& warpedLandmarks68,
|
|
const Transformation& transformation,
|
|
Landmarks68& landmarks68) const noexcept = 0;
|
|
|
|
virtual Result<FSDKError>
|
|
unwarp(
|
|
const GazeEstimation& warpedAngles,
|
|
const Transformation& transformation,
|
|
GazeEstimation& angles
|
|
) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Common aliases for IWarper asynchronous interface.
|
|
* */
|
|
using ImageBatch = std::vector<Image>;
|
|
using ImageBatchFuture = vlc::future<ImageBatch>;
|
|
|
|
/**
|
|
* @brief Asynchronously warp faces on multiple images.
|
|
* @param [in] images span of source images.
|
|
* @param [in] transformations span of transformation structures.
|
|
* @return Future result object with error code and warped image batch.
|
|
* @see Span, Transformation, Image, Result and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* @note this method is experimental and interface may be changed in the future.
|
|
* @note this method is not marked as noexcept and may throw an exception.
|
|
* */
|
|
virtual ImageBatchFuture warpAsync(
|
|
Span<const Image> images,
|
|
Span<const Transformation> transformations) const = 0;
|
|
};
|
|
|
|
}
|