ContourLineExtractor.h

   1 /***********************************************************************
   2 ContourLineExtractor - Class to identify contour lines from a depth image.
   3 Copyright (c) 2015-2016 Oliver Kreylos
   4 Copyright (c) 2020 Scottsdale Community College
   5
   6 This file is part of the Augmented Reality Sandbox (SARndbox).
   7
   8 The Augmented Reality Sandbox is free software; you can redistribute it
   9 and/or modify it under the terms of the GNU General Public License as
  10 published by the Free Software Foundation; either version 2 of the
  11 License, or (at your option) any later version.
  12
  13 The Augmented Reality Sandbox is distributed in the hope that it will be
  14 useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 General Public License for more details.
  17
  18 You should have received a copy of the GNU General Public License along
  19 with the Augmented Reality Sandbox; if not, write to the Free Software
  20 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  21 ***********************************************************************/
  22
  23 #ifndef CONTOURLINEEXTRACTOR_INCLUDED
  24 #define CONTOURLINEEXTRACTOR_INCLUDED
  25
  26 #include <stddef.h>
  27 #include <vector>
  28 #include <Geometry/OrthonormalTransformation.h>
  29 #include <Geometry/Point.h>
  30 #include <Misc/SizedTypes.h>
  31 #include <Threads/Thread.h>
  32 #include <Threads/MutexCond.h>
  33 #include <Threads/TripleBuffer.h>
  34 #include <Images/RGBImage.h>
  35 #include <Kinect/FrameBuffer.h>
  36 #include <Kinect/FrameSource.h>
  37
  38 #include "Types.h"
  39
  40 /* Forward declarations: */
  41 namespace Misc {
  42 template <class ParameterParam>
  43 class FunctionCall;
  44 }
  45
  46 class ContourLineExtractor {
  47     /* Embedded classes: */
  48   public:
  49     typedef Misc::UInt16 DepthPixel; // Type for depth frame pixels
  50     typedef Kinect::FrameSource::DepthCorrection::PixelCorrection PixelDepthCorrection; // Type for per-pixel depth correction factors
  51
  52     struct ContourLabel { // Structure for contour line label position
  53       public:
  54         Point center;  // Label's center in depth image space
  55         double radius; // Label's approximate radius in depth image space
  56         int elevation;
  57     };
  58
  59     struct ContourLine { // Structure for contour lines
  60       public:
  61         Point origin;  // line's starting point in depth image space
  62         std::vector<Point> points; // list of points making the line
  63     };
  64
  65     typedef std::vector<ContourLine> ContourLineList; // Type for lists of contour lines
  66     typedef Misc::FunctionCall<const ContourLineList&> ContourLinesExtractedFunction; // Type for functions called when a new contour line list has been extracted
  67
  68     /* Elements: */
  69   private:
  70     unsigned int depthFrameSize[2]; // Size of incoming depth frames
  71     const PixelDepthCorrection* pixelDepthCorrection; // Buffer of per-pixel depth correction coefficients
  72     PTransform depthProjection; // Projective transformation from depth image space to camera space
  73
  74     Plane basePlane; // Base plane to calculate surface elevation
  75     GLfloat basePlaneDicEq[4]; // Base plane equation in depth image space in GLSL-compatible format
  76
  77     const DepthPixel maxDepth = 0x07ffU - 1U; // depths above this are invalid
  78
  79     Threads::MutexCond inputCond; // Condition variable to signal arrival of a new input frame
  80     Kinect::FrameBuffer inputFrame; // The most recent input frame
  81     unsigned int inputFrameVersion; // Version number of input frame
  82     volatile bool runExtractorThread; // Flag to keep the background extraction thread running
  83     Threads::Thread extractorThread; // The background filtering thread
  84
  85     DepthPixel maxFgDepth; // Maximum depth value for foreground blobs
  86     unsigned int minLineLength; // Minimum number of pixels needed to define a contour line
  87     static const unsigned short invalidLineId; // Invalid contour line ID
  88     static const int walkDx[8]; // Array of edge walking steps in clockwise order in x
  89     static const int walkDy[8]; // Array of edge walking steps in clockwise order in y
  90     ptrdiff_t walkOffsets[8]; // Array of pointer offsets for edge walking steps in clockwise order
  91
  92     Threads::TripleBuffer<ContourLineList> extractedContourLines; // Triple buffer of lists of extracted contour lines
  93     ContourLinesExtractedFunction* contourLinesExtractedFunction; // Function called when a new list of extracted contour lines is ready
  94
  95     /* Private methods: */
  96     void* extractorThreadMethod(void); // Method for the background hand extraction thread
  97
  98     /* Constructors and destructors: */
  99   public:
 100     ContourLineExtractor(const unsigned int sDepthFrameSize[2],
 101                          const PixelDepthCorrection* sPixelDepthCorrection,
 102                          const PTransform& sDepthProjection); // Creates a hand extractor for depth frames of the given size
 103     ~ContourLineExtractor(void);
 104
 105   private:
 106     ContourLineExtractor(const ContourLineExtractor& source); // Prohibit copy constructor
 107     ContourLineExtractor& operator=(const ContourLineExtractor& source); // Prohibit assignment operator
 108
 109   public:
 110     /* Methods: */
 111     DepthPixel getMaxFgDepth(void) const { // Returns the maximum depth value for foreground blobs
 112         return maxFgDepth;
 113     }
 114     void setMaxFgDepth(DepthPixel newMaxFgDepth); // Sets the maximum depth value for foreground blobs
 115
 116     const Plane& getBasePlane(void) const { // Returns the elevation base plane
 117         return basePlane;
 118     }
 119
 120     unsigned int getMinLineLength(void) const { // Returns the minimum number of pixels to consider a blob a hand candidate
 121         return minLineLength;
 122     }
 123
 124     void extractContourLines(const ContourLineExtractor::DepthPixel* depthFrame,
 125                              ContourLineExtractor::ContourLineList& lines); // Extracts contour lines from the given depth frame
 126
 127     void setBasePlane(const Plane& newBasePlane); // Sets a new base plane for elevation rendering
 128     void setContourLinesExtractedFunction(ContourLineExtractor::ContourLinesExtractedFunction* newContourLinesExtractedFunction); // Sets the output function; adopts given functor object
 129
 130     void receiveRawFrame(const Kinect::FrameBuffer& newFrame); // Called to receive a new raw depth frame
 131
 132     bool lockNewExtractedContourLines(void) { // Locks the most recently produced output list of extracted contour lines for reading; returns true if the locked list is new
 133         return extractedContourLines.lockNewValue();
 134     }
 135     const ContourLineList& getLockedExtractedContourLines(void) const { // Returns the most recently locked output list of extracted contour lines
 136         return extractedContourLines.getLockedValue();
 137     }
 138 };
 139
 140 #endif