VisionAPI.cpp

/********************************************************************************
*  Project              : FIRST Motor Controller
*  File Name            : VisionAPI.cpp        
*  Contributors         : ELF, EMF
*  Creation Date        : June 26, 2008
*  Revision History     : Source code & revision history maintained at sourceforge.WPI.edu   
*  File Description     : C Routines for FIRST Vision API. Open source API developed 
*    by BAE Systems to interface with the National Instruments vision C library
*    in the nivision.out module. The published interface to nivision.out is in
*    the header file nivision.h and documented in the NIVisionCVI.chm help file.
*/ 
/*----------------------------------------------------------------------------*/
/*        Copyright (c) FIRST 2008.  All Rights Reserved.                     */
/*  Open Source Software - may be modified and shared by FRC teams. The code  */
/*  must be accompanied by the FIRST BSD license file in $(WIND_BASE)/WPILib. */
/*----------------------------------------------------------------------------*/

#include "stdioLib.h" 
#include "vxWorks.h" 

#include "BaeUtilities.h"
#include "FrcError.h"
#include "VisionAPI.h" 

int VisionAPI_debugFlag = 1;
#define DPRINTF if(VisionAPI_debugFlag)dprintf

/*   Image Management functions    */

Image* frcCreateImage(ImageType type) { return imaqCreateImage(type, DEFAULT_BORDER_SIZE); }

int frcDispose(void* object)  { return imaqDispose(object);     }
int frcDispose( const char* functionName, ... ) /* Variable argument list */
{
    va_list disposalPtrList;   /* Input argument list */
    void* disposalPtr;         /* For iteration */
    int success, returnValue = 1;
    
    va_start( disposalPtrList, functionName );  /* start of variable list */
    disposalPtr = va_arg( disposalPtrList, void* );
    while( disposalPtr != NULL )     {
        success = imaqDispose(disposalPtr);
        if (!success) {returnValue = 0;}
        disposalPtr = va_arg( disposalPtrList, void* );
    }
    return returnValue;
}

int frcCopyImage(Image* dest, const Image* source) { return imaqDuplicate(dest, source);  }

int frcCrop(Image* dest, const Image* source, Rect rect)
{       
        return imaqScale(dest, source, 1, 1, IMAQ_SCALE_LARGER, rect);
}


int frcScale(Image* dest, const Image* source, int xScale, int yScale, ScalingMode scaleMode)
{       
        Rect rect = IMAQ_NO_RECT;
        return imaqScale(dest, source, xScale, yScale, scaleMode, rect);        
}
  
 int frcReadImage(Image* image, const char* fileName)
 {
         return imaqReadFile(image, fileName, NULL, NULL);
 }


int frcWriteImage(const Image* image, const char* fileName)
{       
        RGBValue* colorTable = NULL;
        return imaqWriteFile(image, fileName, colorTable);
}


/*  Measure Intensity functions */

HistogramReport* frcHistogram(const Image* image, int numClasses, float min, float max)
{
        Rect rect = IMAQ_NO_RECT;
        return frcHistogram(image, numClasses, min, max, rect);         
}
HistogramReport* frcHistogram(const Image* image, int numClasses, float min, float max, Rect rect)
{
        int success; 
        int fillValue = 1;
        
        /* create the region of interest */
        ROI* pRoi = imaqCreateROI();
        success = imaqAddRectContour(pRoi, rect); 
        if ( !success ) { GetLastVisionError(); return NULL; }  

        /* make a mask from the ROI */
        Image* pMask = frcCreateImage(IMAQ_IMAGE_U8);
        success = imaqROIToMask(pMask, pRoi, fillValue, NULL, NULL);
        if ( !success ) { 
                GetLastVisionError(); 
                frcDispose(__FUNCTION__, pRoi, NULL); 
                return NULL; 
        }       
        
        /* get a histogram report */
        HistogramReport* pHr = NULL;
        pHr = imaqHistogram(image, numClasses, min, max, pMask); 
        
        /* clean up */
        frcDispose(__FUNCTION__, pRoi, pMask, NULL); 
        
        return pHr;
}

ColorHistogramReport* frcColorHistogram(const Image* image, int numClasses, ColorMode mode)
{       
        return frcColorHistogram(image, numClasses, mode, NULL);
}

ColorHistogramReport* frcColorHistogram(const Image* image, int numClasses, ColorMode mode, Image* mask)
{
        return imaqColorHistogram2((Image*)image, numClasses, mode, NULL, mask);
}


int frcGetPixelValue(const Image* image, Point pixel, PixelValue* value)
{       
        return imaqGetPixel(image, pixel, value);
}


/*   Particle Analysis functions */

int frcParticleFilter(Image* dest, Image* source, const ParticleFilterCriteria2* criteria, 
                int criteriaCount, const ParticleFilterOptions* options, int* numParticles)
{
        Rect rect = IMAQ_NO_RECT;
        return frcParticleFilter(dest, source, criteria, criteriaCount, options, rect, numParticles);
}

int frcParticleFilter(Image* dest, Image* source, const ParticleFilterCriteria2* criteria, 
                int criteriaCount, const ParticleFilterOptions* options, Rect rect, int* numParticles)
{
        ROI* roi = imaqCreateROI();
        imaqAddRectContour(roi, rect);
        return imaqParticleFilter3(dest, source, criteria, criteriaCount, options, roi, numParticles);
}


int frcMorphology(Image* dest, Image* source, MorphologyMethod method)
{       
        return imaqMorphology(dest, source, method, NULL);
}

int frcMorphology(Image* dest, Image* source, MorphologyMethod method, const StructuringElement* structuringElement)
{       
        return imaqMorphology(dest, source, method, structuringElement); 
}

int frcRejectBorder(Image* dest, Image* source)
{       return imaqRejectBorder(dest, source, TRUE); }

int frcRejectBorder(Image* dest, Image* source, int connectivity8)
{       
        return imaqRejectBorder(dest, source, connectivity8);
}


int frcCountParticles(Image* image, int* numParticles)                          
{       
        return imaqCountParticles(image, 1, numParticles);
}


int frcParticleAnalysis(Image* image, int particleNumber, ParticleAnalysisReport* par)                          
{
        int success = 0;

        /* image information */
        int height, width;
        if ( ! imaqGetImageSize(image, &width, &height) )       { return success; }     
        par->imageWidth = width;        
        par->imageHeight = height;      
        par->particleIndex = particleNumber;            

        /* center of mass point of the largest particle */
        double returnDouble;
        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_CENTER_OF_MASS_X, &returnDouble);
        if ( !success ) { return success; }
        par->center_mass_x = (int)returnDouble;                                         // pixel        

        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_CENTER_OF_MASS_Y, &returnDouble);       
        if ( !success ) { return success; }
        par->center_mass_y = (int)returnDouble;                                         // pixel                
        
        /* particle size statistics */ 
        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_AREA, &returnDouble);   
        if ( !success ) { return success; }
        par->particleArea = returnDouble;       
        
        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_BOUNDING_RECT_TOP, &returnDouble);      
        if ( !success ) { return success; }
        par->boundingRect.top = (int)returnDouble;
        
        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_BOUNDING_RECT_LEFT, &returnDouble);     
        if ( !success ) { return success; }
        par->boundingRect.left = (int)returnDouble;
        
        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_BOUNDING_RECT_HEIGHT, &returnDouble);   
        if ( !success ) { return success; }
        par->boundingRect.height = (int)returnDouble;   

        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_BOUNDING_RECT_WIDTH, &returnDouble);    
        if ( !success ) { return success; }
        par->boundingRect.width = (int)returnDouble;    
        
        /* particle quality statistics */ 
        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_AREA_BY_IMAGE_AREA, &returnDouble);     
        if ( !success ) { return success; }
        par->particleToImagePercent = returnDouble;

        success = imaqMeasureParticle(image, particleNumber, 0, IMAQ_MT_AREA_BY_PARTICLE_AND_HOLES_AREA, &returnDouble);        
        if ( !success ) { return success; }
        par->particleQuality = returnDouble;
                
        /* normalized position (-1 to 1) */
        par->center_mass_x_normalized = RangeToNormalized(par->center_mass_x, width);
        par->center_mass_y_normalized = RangeToNormalized(par->center_mass_y, height);  
        
        return success;
}


/*   Image Enhancement functions */

int frcEqualize(Image* dest, const Image* source, float min, float max)
{       return frcEqualize(dest, source, min, max, NULL);  }

int frcEqualize(Image* dest, const Image* source, float min, float max, const Image* mask)
{
        return imaqEqualize(dest, source, min, max, mask);
}

int frcColorEqualize(Image* dest, const Image* source)
{
        return imaqColorEqualize(dest, source, TRUE);
}

int frcColorEqualize(Image* dest, const Image* source, int colorEqualization)
{
        return imaqColorEqualize(dest, source, TRUE);
}

/*   Image Conversion functions */

int frcSmartThreshold(Image* dest, const Image* source, 
                unsigned int windowWidth, unsigned int windowHeight, LocalThresholdMethod method, 
                double deviationWeight, ObjectType type)
{
        float replaceValue = 1.0;
        return imaqLocalThreshold(dest, source, windowWidth, windowHeight, method, 
                        deviationWeight, type, replaceValue);
}

int frcSmartThreshold(Image* dest, const Image* source, 
                unsigned int windowWidth, unsigned int windowHeight, LocalThresholdMethod method, 
                double deviationWeight, ObjectType type, float replaceValue)
{
        return imaqLocalThreshold(dest, source, windowWidth, windowHeight, method, 
                        deviationWeight, type, replaceValue);
}

int frcSimpleThreshold(Image* dest, const Image* source, float rangeMin, float rangeMax)
{
        int newValue = 255;
        return frcSimpleThreshold(dest, source, rangeMin, rangeMax, newValue);
}

int frcSimpleThreshold(Image* dest, const Image* source, float rangeMin, float rangeMax, float newValue)
{
        int useNewValue = TRUE;
        return imaqThreshold(dest, source, rangeMin, rangeMax, useNewValue, newValue);
}

int frcColorThreshold(Image* dest, const Image* source, ColorMode mode, 
                const Range* plane1Range, const Range* plane2Range, const Range* plane3Range)
{
        int replaceValue = 1;
        return imaqColorThreshold(dest, source, replaceValue, mode, plane1Range, plane2Range, plane3Range);
}

int frcColorThreshold(Image* dest, const Image* source, int replaceValue, ColorMode mode, 
                const Range* plane1Range, const Range* plane2Range, const Range* plane3Range)
{       return imaqColorThreshold(dest, source, replaceValue, mode, plane1Range, plane2Range, plane3Range);}


int frcHueThreshold(Image* dest, const Image* source, const Range* hueRange)
{ return frcHueThreshold(dest, source, hueRange, DEFAULT_SATURATION_THRESHOLD); }

int frcHueThreshold(Image* dest, const Image* source, const Range* hueRange, int minSaturation)
{
        // assume HSL mode
        ColorMode mode = IMAQ_HSL;  
        // Set saturation 100 - 255
        Range satRange;  satRange.minValue = minSaturation; satRange.maxValue = 255;
        // Set luminance 100 - 255
        Range lumRange;  lumRange.minValue = 100; lumRange.maxValue = 255;
        // Replace pixels with 1 if pass threshold filter
        int replaceValue = 1;
        return imaqColorThreshold(dest, source, replaceValue, mode, hueRange, &satRange, &lumRange);
}

int frcExtractColorPlanes(const Image* image, ColorMode mode, 
                Image* plane1, Image* plane2, Image* plane3)
{       return imaqExtractColorPlanes(image, mode, plane1, plane2, plane3); }

int frcExtractHuePlane(const Image* image, Image* huePlane)
{
        return frcExtractHuePlane(image, huePlane, DEFAULT_SATURATION_THRESHOLD);
}

int frcExtractHuePlane(const Image* image, Image* huePlane, int minSaturation)
{
        return frcExtractColorPlanes(image, IMAQ_HSL, huePlane, NULL, NULL);
}