wpilibc/Athena/include/Vision/VisionAPI.h

/*----------------------------------------------------------------------------*/
/* Copyright (c) FIRST 2014. 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.  */
/*----------------------------------------------------------------------------*/

#pragma once

#include "nivision.h"

/*   Constants */

#define DEFAULT_BORDER_SIZE 3  // VisionAPI.frcCreateImage
#define DEFAULT_SATURATION_THRESHOLD 40  // TrackAPI.FindColor

/*   Forward Declare Data Structures */
typedef struct FindEdgeOptions_struct FindEdgeOptions;
typedef struct CircularEdgeReport_struct CircularEdgeReport;

/*   Data Structures */

/**  frcParticleAnalysis returns this structure */
typedef struct ParticleAnalysisReport_struct {
  int imageHeight;
  int imageWidth;
  double imageTimestamp;
  int particleIndex;  // the particle index analyzed
  /* X-coordinate of the point representing the average position of the
   * total particle mass, assuming every point in the particle has a constant
   * density */
  int center_mass_x;  // MeasurementType: IMAQ_MT_CENTER_OF_MASS_X
  /* Y-coordinate of the point representing the average position of the
   * total particle mass, assuming every point in the particle has a constant
   * density */
  int center_mass_y;  // MeasurementType: IMAQ_MT_CENTER_OF_MASS_Y
  double center_mass_x_normalized;  // Center of mass x value normalized to -1.0
                                    // to +1.0 range
  double center_mass_y_normalized;  // Center of mass y value normalized to -1.0
                                    // to +1.0 range
  /* Area of the particle */
  double particleArea;  // MeasurementType: IMAQ_MT_AREA
  /* Bounding Rectangle */
  Rect boundingRect;  // left/top/width/height
  /* Percentage of the particle Area covering the Image Area. */
  double particleToImagePercent;  // MeasurementType: IMAQ_MT_AREA_BY_IMAGE_AREA
  /* Percentage of the particle Area in relation to its Particle and Holes Area
   */
  double particleQuality;  // MeasurementType:
                           // IMAQ_MT_AREA_BY_PARTICLE_AND_HOLES_AREA
} ParticleAnalysisReport;

/** Tracking functions return this structure */
typedef struct ColorReport_struct {
  int numberParticlesFound;   // Number of particles found for this color
  int largestParticleNumber;  // The particle index of the largest particle
  /* Color information */
  float particleHueMax;   // HistogramReport: hue max
  float particleHueMin;   // HistogramReport: hue max
  float particleHueMean;  // HistogramReport: hue mean
  float particleSatMax;   // HistogramReport: saturation max
  float particleSatMin;   // HistogramReport: saturation max
  float particleSatMean;  // HistogramReport: saturation mean
  float particleLumMax;   // HistogramReport: luminance max
  float particleLumMin;   // HistogramReport: luminance  max
  float particleLumMean;  // HistogramReport: luminance mean
} ColorReport;

/*   Image Management functions */

/* Create: calls imaqCreateImage. Border size is set to some default value */
Image* frcCreateImage(ImageType type);

/* Dispose: calls imaqDispose */
int frcDispose(void* object);
int frcDispose(const char* filename, ...);

/* Copy: calls imaqDuplicateImage */
int frcCopyImage(Image* dest, const Image* source);

/* Image Extraction: Crop: calls imaqScale */
int frcCrop(Image* dest, const Image* source, Rect rect);

/* Image Extraction: Scale: calls imaqScale.  Scales entire image */
int frcScale(Image* dest, const Image* source, int xScale, int yScale,
             ScalingMode scaleMode);

/* Read Image : calls imaqReadFile */
int frcReadImage(Image* image, const char* fileName);
/* Write Image : calls imaqWriteFile */
int frcWriteImage(const Image* image, const char* fileName);

/*   Measure Intensity functions */

/* Histogram: calls imaqHistogram */
HistogramReport* frcHistogram(const Image* image, int numClasses, float min,
                              float max, Rect rect);
/* Color Histogram: calls imaqColorHistogram2 */
ColorHistogramReport* frcColorHistogram(const Image* image, int numClasses,
                                        ColorMode mode, Image* mask);

/* Get Pixel Value: calls imaqGetPixel */
int frcGetPixelValue(const Image* image, Point pixel, PixelValue* value);

/*   Particle Analysis functions */

/* Particle Filter: calls imaqParticleFilter3 */
int frcParticleFilter(Image* dest, Image* source,
                      const ParticleFilterCriteria2* criteria,
                      int criteriaCount, const ParticleFilterOptions* options,
                      Rect rect, int* numParticles);
int frcParticleFilter(Image* dest, Image* source,
                      const ParticleFilterCriteria2* criteria,
                      int criteriaCount, const ParticleFilterOptions* options,
                      int* numParticles);
/* Morphology: calls imaqMorphology */
int frcMorphology(Image* dest, Image* source, MorphologyMethod method);
int frcMorphology(Image* dest, Image* source, MorphologyMethod method,
                  const StructuringElement* structuringElement);
/* Reject Border: calls imaqRejectBorder */
int frcRejectBorder(Image* dest, Image* source);
int frcRejectBorder(Image* dest, Image* source, int connectivity8);
/* Count Particles: calls imaqCountParticles */
int frcCountParticles(Image* image, int* numParticles);
/* Particle Analysis Report: calls imaqMeasureParticle */
int frcParticleAnalysis(Image* image, int particleNumber,
                        ParticleAnalysisReport* par);

/*   Image Enhancement functions */

/* Equalize: calls imaqEqualize */
int frcEqualize(Image* dest, const Image* source, float min, float max);
int frcEqualize(Image* dest, const Image* source, float min, float max,
                const Image* mask);

/* Color Equalize: calls imaqColorEqualize */
int frcColorEqualize(Image* dest, const Image* source);
int frcColorEqualize(Image* dest, const Image* source, int colorEqualization);

/*   Image Thresholding & Conversion functions */

/* Smart Threshold: calls imaqLocalThreshold */
int frcSmartThreshold(Image* dest, const Image* source,
                      unsigned int windowWidth, unsigned int windowHeight,
                      LocalThresholdMethod method, double deviationWeight,
                      ObjectType type);
int frcSmartThreshold(Image* dest, const Image* source,
                      unsigned int windowWidth, unsigned int windowHeight,
                      LocalThresholdMethod method, double deviationWeight,
                      ObjectType type, float replaceValue);

/* Simple Threshold: calls imaqThreshold */
int frcSimpleThreshold(Image* dest, const Image* source, float rangeMin,
                       float rangeMax, float newValue);
int frcSimpleThreshold(Image* dest, const Image* source, float rangeMin,
                       float rangeMax);

/* Color/Hue Threshold: calls imaqColorThreshold */
int frcColorThreshold(Image* dest, const Image* source, ColorMode mode,
                      const Range* plane1Range, const Range* plane2Range,
                      const Range* plane3Range);
int frcColorThreshold(Image* dest, const Image* source, int replaceValue,
                      ColorMode mode, const Range* plane1Range,
                      const Range* plane2Range, const Range* plane3Range);
int frcHueThreshold(Image* dest, const Image* source, const Range* hueRange);
int frcHueThreshold(Image* dest, const Image* source, const Range* hueRange,
                    int minSaturation);

/* Extract ColorHue Plane: calls imaqExtractColorPlanes */
int frcExtractColorPlanes(const Image* image, ColorMode mode, Image* plane1,
                          Image* plane2, Image* plane3);
int frcExtractHuePlane(const Image* image, Image* huePlane);
int frcExtractHuePlane(const Image* image, Image* huePlane, int minSaturation);