HandExtractor.h

/***********************************************************************
HandExtractor - Class to identify hands from a depth image.
Copyright (c) 2015-2016 Oliver Kreylos
Copyright (c) 2019 Scottsdale Community College

This file is part of the Augmented Reality Sandbox (SARndbox).

The Augmented Reality Sandbox is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.

The Augmented Reality Sandbox is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License along
with the Augmented Reality Sandbox; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
***********************************************************************/

#ifndef HANDEXTRACTOR_INCLUDED
#define HANDEXTRACTOR_INCLUDED

#include <stddef.h>
#include <vector>
#include <Misc/SizedTypes.h>
#include <Threads/Thread.h>
#include <Threads/MutexCond.h>
#include <Threads/TripleBuffer.h>
#include <Images/RGBImage.h>
#include <Kinect/FrameBuffer.h>
#include <Kinect/FrameSource.h>

#include "Types.h"

/* Forward declarations: */
namespace Misc {
template <class ParameterParam>
class FunctionCall;
}

class HandExtractor {
    /* Embedded classes: */
public:
    typedef Misc::UInt16 DepthPixel; // Type for depth frame pixels
    typedef Kinect::FrameSource::DepthCorrection::PixelCorrection
    PixelDepthCorrection; // Type for per-pixel depth correction factors

    struct Hand { // Structure to report detected hand positions
        /* Elements: */
    public:
        Point center; // Hand's center in depth image space
        double radius; // Hand's approximate radius in depth image space
        int direction; // positive for rain, negative for evaporation
    };

    typedef std::vector<Hand> HandList; // Type for lists of hand positions
    typedef Misc::FunctionCall<const HandList&>
    HandsExtractedFunction; // Type for functions called when a new hand list has been extracted

private:
    struct EdgePixel { // Helper structure storing an edge pixel of a blob
        /* Elements: */
    public:
        int x, y; // Position of edge pixel in depth frame
        const unsigned short* biPtr; // Pointer to edge pixel in blob ID image
    };

    /* Elements: */
private:
    unsigned int depthFrameSize[2]; // Size of incoming depth frames
    const PixelDepthCorrection*
    pixelDepthCorrection; // Buffer of per-pixel depth correction coefficients
    PTransform depthProjection; // Projective transformation from depth image space to camera space

    Threads::MutexCond inputCond; // Condition variable to signal arrival of a new input frame
    Kinect::FrameBuffer inputFrame; // The most recent input frame
    unsigned int inputFrameVersion; // Version number of input frame
    volatile bool runExtractorThread; // Flag to keep the background extraction thread running
    Threads::Thread extractorThread; // The background filtering thread

    DepthPixel maxFgDepth; // Maximum depth value for foreground blobs
    unsigned int
    maxDepthDist; // Maximum depth distance between adjacent pixels to belong to the same foreground blob
    unsigned int minBlobSize,
             maxBlobSize; // Minimum and maximum number of pixels to consider a blob a hand candidate
    unsigned short* blobIdImage; // Image of per-pixel blob IDs with one pixel boundary layer
    ptrdiff_t biStride; // Row stride in blob ID image
    static const unsigned short invalidBlobId; // Invalid blob ID
    static const int walkDx[8]; // Array of edge walking steps in clockwise order in x
    static const int walkDy[8]; // Array of edge walking steps in clockwise order in y
    ptrdiff_t walkOffsets[8]; // Array of pointer offsets for edge walking steps in clockwise order
    unsigned int snakeLength; // Length of the "snake" walking around blobs' edges to detect corners
    EdgePixel* snake; // Array of snake's pixels
    int maxCornerEnterDist; // Maximum distance between snake's head and tail to enter corner state
    int minCenterDist; // Minimum distance from snake's center to line defined by its head and tail to enter corner state
    int minCornerExitDist; // Minimum distance between snake's head and tail to leave corner state
    float minHandProbability; // Minimum probability rating at which to accept a blob as a hand

    Threads::TripleBuffer<HandList> extractedHands; // Triple buffer of lists of extracted hands
    HandsExtractedFunction*
    handsExtractedFunction; // Function called when a new list of extracted hands is ready

    /* Private methods: */
    void* extractorThreadMethod(void); // Method for the background hand extraction thread

    /* Constructors and destructors: */
public:
    HandExtractor(const unsigned int sDepthFrameSize[2],
                  const PixelDepthCorrection* sPixelDepthCorrection,
                  const PTransform& sDepthProjection); // Creates a hand extractor for depth frames of the given size
private:
    HandExtractor(const HandExtractor& source); // Prohibit copy constructor
    HandExtractor& operator=(const HandExtractor& source); // Prohibit assignment operator
public:
    ~HandExtractor(void);

    /* Methods: */
    DepthPixel getMaxFgDepth(void) const { // Returns the maximum depth value for foreground blobs
        return maxFgDepth;
    }
    void setMaxFgDepth(DepthPixel newMaxFgDepth); // Sets the maximum depth value for foreground blobs
    unsigned int getMaxDepthDist(void)
    const { // Returns the maximum depth distance between adjacent pixels to belong to the same foreground blob
        return maxDepthDist;
    }
    void setMaxDepthDist(unsigned int
                         newMaxDepthDist); // Sets the maximum depth distance between adjacent pixels to belong to the same foreground blob
    unsigned int getMinBlobSize(void)
    const { // Returns the minimum number of pixels to consider a blob a hand candidate
        return minBlobSize;
    }
    unsigned int getMaxBlobSize(void)
    const { // Returns the maximum number of pixels to consider a blob a hand candidate
        return minBlobSize;
    }
    void setBlobSizeRange(unsigned int newMinBlobSize,
                          unsigned int newMaxBlobSize); // Sets the range of numbers of pixels to consider a blob a hand candidate
    unsigned int getSnakeLength(void) const { // Returns the length of the corner detection "snake"
        return snakeLength;
    }
    void setSnakeLength(unsigned int
                        newSnakeLength); // Sets the length of the corner detection "snake"
    int getMaxCornerEnterDist(void)
    const { // Returns the maximum distance between snake's head and tail to enter corner state
        return maxCornerEnterDist;
    }
    int getMinCenterDist(void)
    const { // Returns the minimum distance from snake's center to line defined by its head and tail to enter corner state
        return minCenterDist;
    }
    int getMinCornerExitDist(void)
    const { // Returns the minimum distance between snake's head and tail to exit corner state
        return minCornerExitDist;
    }
    void setCornerDists(int newMaxCornerEnterDist, int newMinCenterDist,
                        int newMinCornerExitDist); // Sets distances between snake's head and tail to enter and exit corner state, respectively
    void extractHands(const DepthPixel* depthFrame, HandList& hands,
                      Images::RGBImage* blobImage); // Extracts hands from the given depth frame
    void setHandsExtractedFunction(HandsExtractedFunction*
                                   newHandsExtractedFunction); // Sets the output function; adopts given functor object
    void receiveRawFrame(const Kinect::FrameBuffer&
                         newFrame); // Called to receive a new raw depth frame
    bool lockNewExtractedHands(
        void) { // Locks the most recently produced output list of extracted hands for reading; returns true if the locked list is new
        return extractedHands.lockNewValue();
    }
    const HandList& getLockedExtractedHands(void)
    const { // Returns the most recently locked output list of extracted hands
        return extractedHands.getLockedValue();
    }
};

#endif