Feature Detection
[Vision Package]

Classes
struct	RGBGrad
struct	Gan_CornerFeature
	2D corner feature structure. More...
struct	Gan_CornerFeatureMap
	2D corner feature map structure. More...
struct	Gan_EdgeFeature
	2D edge feature structure More...
struct	Gan_EdgeString
	Structure defining a connected string of edge features. More...
struct	Gan_EdgeFeatureMap
	Definition of 2D edge feature map structure. More...
struct	Gan_LineFeature
	2D line feature structure. More...
struct	Gan_LineFeatureMap
	2D line feature map structure. More...
struct	Gan_LocalFeatureMap
	Structure to hold blocked local feature information. More...
struct	Gan_LocalFeatureMapParams
	Structure to hold parameters for blocked local features. More...
Defines
#define	GAN_ISOLATED   0
#define	GAN_IN_STRING   1024
#define	ORIENT_MASK   0x3f
#define	ATAN_NUMBER   100
#define	ATAN_NUMBER_F   100.0F
#define	THREE_OVER_TWO   1.5F
#define	TWO_OVER_THREE   0.6667F
#define	THOUSAND   1000.0F
#define	RADIAN_TEN   5.729577951F
#define	EIGHTEEN_AND_A_BIT   18.5F
#define	FEATURE_ARRAY_STEP_SIZE   500
#define	FEATURE_ARRAY_STEP_SIZE   500
#define	FEATURE_ARRAY_STEP_SIZE   500
#define	POINT_ARRAY_REALLOC_SIZE   5000
Typedefs
typedef RGBGrad	RGBGrad
typedef Gan_CornerFeature	Gan_CornerFeature
	2D corner feature structure.
typedef Gan_CornerFeatureMap	Gan_CornerFeatureMap
	2D corner feature map structure.
typedef Gan_EdgeFeature	Gan_EdgeFeature
	2D edge feature structure
typedef Gan_EdgeString	Gan_EdgeString
	Structure defining a connected string of edge features.
typedef Gan_EdgeFeatureMap	Gan_EdgeFeatureMap
	Definition of 2D edge feature map structure.
typedef Gan_LineFeature	Gan_LineFeature
	2D line feature structure.
typedef Gan_LineFeatureMap	Gan_LineFeatureMap
	2D line feature map structure.
typedef Gan_LocalFeatureMap	Gan_LocalFeatureMap
	Structure to hold blocked local feature information.
typedef Gan_LocalFeatureMapParams	Gan_LocalFeatureMapParams
	Structure to hold parameters for blocked local features.
Functions
Gan_EdgeFeatureMap *	gan_canny_edge_q (Gan_Image *image, Gan_Image *mask, Gan_Mask1D *filter_y, Gan_Mask1D *filter_x, Gan_RGBPixel_f *colour, Gan_Vector2_f *direction, double lower_thres, double upper_thres, unsigned string_length_thres, Gan_Matrix23_f *A, Gan_Camera *camera, Gan_LocalFeatureMapParams *lpms, Gan_EdgeFeatureMap *edge_map, void(*set_progress)(void *, unsigned), void *progress_obj)
	Computes edges in an image using the Canny algorithm.
Gan_EdgeFeatureMap *	gan_canny_edge_s (Gan_Image *image, Gan_Image *mask, Gan_Mask1D *filter_y, Gan_Mask1D *filter_x, Gan_RGBPixel_f *colour, Gan_Vector2_f *direction, double lower_thres, double upper_thres, unsigned string_length_thres, Gan_Matrix23_f *A, Gan_Camera *camera, Gan_LocalFeatureMapParams *lpms, void(*set_progress)(void *, unsigned), void *progress_obj)
	Macro: Computes edges in an image using the Canny algorithm.
Gan_Bool	gan_corner_feature_display (Gan_CornerFeature *corner, float size, Gan_Matrix23_f *A, Gan_RGBPixel_f *corner_colour)
	Displays a single corner feature.
Gan_Bool	gan_corner_feature_map_display (Gan_CornerFeatureMap *cmap, float size, Gan_Matrix23_f *A, Gan_RGBPixel_f *corner_colour, Gan_RGBPixel_f *bbox_colour)
	Displays a corner feature map.
Gan_CornerFeatureMap *	gan_corner_feature_map_form (Gan_CornerFeatureMap *cmap, unsigned max_ncorners)
	Forms a corner feature map structure.
void	gan_corner_feature_map_free (Gan_CornerFeatureMap *cmap)
	Frees a corner feature map structure.
Gan_Bool	gan_corner_feature_map_clear (Gan_CornerFeatureMap *cmap, unsigned height, unsigned width, Gan_Matrix23_f *A, Gan_Camera *camera, Gan_LocalFeatureMapParams *lpms)
	Sets up and clears a corner feature map structure.
Gan_CornerFeature *	gan_corner_feature_add (Gan_CornerFeatureMap *cmap, unsigned r, unsigned c, float rf, float cf, Gan_SquMatrix22_f *N, int status, int index, float strength)
	Adds a corner to a corner feature map.
Gan_Bool	gan_corner_feature_map_postprocess (Gan_CornerFeatureMap *cmap)
	Postprocess feature map.
Gan_CornerFeatureMap *	gan_corner_feature_map_alloc (unsigned max_ncorners)
	Macro: Allocates a corner feature map structure.
Gan_Bool	gan_edge_feature_display (Gan_EdgeFeature *edge, float size, Gan_Matrix23_f *A, Gan_RGBPixel_f *edge_colour)
	Displays a single edge feature.
Gan_Bool	gan_edge_feature_map_display (Gan_EdgeFeatureMap *emap, float size, Gan_Matrix23_f *A, Gan_RGBPixel_f *edge_colour, Gan_RGBPixel_f *string_colour, Gan_RGBPixel_f *first_colour, Gan_RGBPixel_f *last_colour, Gan_RGBPixel_f *bbox_colour)
	Displays a edge feature map.
Gan_EdgeFeatureMap *	gan_edge_feature_map_form (Gan_EdgeFeatureMap *emap, unsigned max_nedges, unsigned max_nstrings)
	Forms an edge feature map structure.
void	gan_edge_feature_map_free (Gan_EdgeFeatureMap *emap)
	Frees an edge feature map structure.
Gan_Bool	gan_edge_feature_map_clear (Gan_EdgeFeatureMap *emap, unsigned height, unsigned width, Gan_Matrix23_f *A, Gan_Camera *camera, Gan_LocalFeatureMapParams *lpms)
	Sets up and clears an edge feature map structure.
Gan_EdgeFeature *	gan_edge_feature_add (Gan_EdgeFeatureMap *emap, unsigned r, unsigned c, float rf, float cf, float angle, float cov, int status, int index, float strength)
	Adds an edge to an edge feature map.
Gan_EdgeString *	gan_edge_feature_string_add (Gan_EdgeFeatureMap *emap, Gan_EdgeFeature *edge)
	Adds an edge string to an edge feature map.
Gan_Bool	gan_edge_feature_string_set_status (Gan_EdgeString *string, int status)
	Sets the status of all edges in the string.
Gan_Bool	gan_edge_feature_map_postprocess (Gan_EdgeFeatureMap *emap)
	Postprocess feature map.
Gan_EdgeFeatureMap *	gan_edge_feature_map_alloc (unsigned max_nedges, unsigned max_nstrings)
	Macro: Allocates a edge feature map structure.
Gan_CornerFeatureMap *	gan_harris_corner_q (Gan_Image *image, Gan_Image *mask, Gan_Mask1D *image_filter_y, Gan_Mask1D *image_filter_x, Gan_Mask1D *grad_filter_y, Gan_Mask1D *grad_filter_x, float kappa, float thres, Gan_Matrix23_f *A, int status, Gan_Camera *camera, Gan_LocalFeatureMapParams *lpms, Gan_CornerFeatureMap *corner_map)
	Computes corners in an image using the Harris algorithm.
Gan_CornerFeatureMap *	gan_harris_corner_s (Gan_Image *image, Gan_Image *mask, Gan_Mask1D *image_filter_y, Gan_Mask1D *image_filter_x, Gan_Mask1D *grad_filter_y, Gan_Mask1D *grad_filter_x, float kappa, float thres, Gan_Matrix23_f *A, int status, Gan_Camera *camera, Gan_LocalFeatureMapParams *lpms)
	Macro: Computes corners in an image using the Harris algorithm.
Gan_Bool	gan_line_feature_display (Gan_LineFeature *line, float line_thickness, Gan_Matrix23_f *A, Gan_RGBPixel_f *line_colour, Gan_RGBPixel_f *first_colour, Gan_RGBPixel_f *last_colour, Gan_RGBPixel_f *point_colour)
	Displays a single line feature.
Gan_Bool	gan_line_feature_map_display (Gan_LineFeatureMap *lmap, float line_thickness, Gan_Matrix23_f *A, Gan_RGBPixel_f *line_colour, Gan_RGBPixel_f *first_colour, Gan_RGBPixel_f *last_colour, Gan_RGBPixel_f *point_colour, Gan_RGBPixel_f *bbox_colour)
	Displays a line feature map.
Gan_LineFeatureMap *	gan_line_feature_map_form (Gan_LineFeatureMap *lmap, unsigned max_nlines)
	Forms a line feature map structure.
Gan_LineFeatureMap *	gan_line_feature_map_copy (Gan_LineFeatureMap *lmap)
	Copies a line feature map structure.
void	gan_line_feature_map_free (Gan_LineFeatureMap *lmap)
	Frees a line feature map structure.
Gan_Bool	gan_line_feature_map_clear (Gan_LineFeatureMap *lmap, unsigned height, unsigned width, Gan_Matrix23_f *A, Gan_LocalFeatureMapParams *lpms)
	Sets up and clears a line feature map structure.
Gan_LineFeature *	gan_line_feature_add (Gan_LineFeatureMap *lmap, float y1, float x1, float y2, float x2, Gan_SquMatrix22_f *N, int status, int index, float strength, Gan_Vector2_f *point, unsigned npoints)
	Adds a line to a line feature map.
Gan_Bool	gan_line_feature_map_postprocess (Gan_LineFeatureMap *lmap)
	Postprocess feature map.
Gan_LineFeatureMap *	gan_line_feature_map_alloc (unsigned max_nlines)
	Macro: Allocates a line feature map structure.
Gan_LocalFeatureMap *	gan_local_feature_map_form (Gan_LocalFeatureMap *pmap, unsigned height, unsigned width, Gan_LocalFeatureMapParams *pms)
	Forms a local feature map structure.
void	gan_local_feature_map_free (Gan_LocalFeatureMap *pmap)
	Frees a local feature map structure.
Gan_Bool	gan_local_feature_map_clear (Gan_LocalFeatureMap *pmap, unsigned height, unsigned width, Gan_LocalFeatureMapParams *pms)
	Clears a local feature map structure.
Gan_Bool	gan_local_feature_point_add (Gan_LocalFeatureMap *pmap, unsigned r, unsigned c, unsigned index)
	Adds a point feature to a local feature map.
Gan_Bool	gan_local_feature_line_add (Gan_LocalFeatureMap *pmap, unsigned r1, unsigned c1, unsigned r2, unsigned c2, unsigned index)
	Adds a line feature to a local feature map.
Gan_Bool	gan_local_feature_map_set_indices (Gan_LocalFeatureMap *pmap)
	Sets indices for a local feature map.
Gan_Bool	gan_local_feature_map_find_block (Gan_LocalFeatureMap *pmap, double y, double x, Gan_Matrix23 *Ai, unsigned *cr, unsigned *cc)
	Computes the block a feature position lies in.
Gan_LocalFeatureMap *	gan_local_feature_map_alloc (unsigned height, unsigned width, Gan_LocalFeatureMapParams *pms)
	Macro: Allocates a local feature map structure.
Gan_LineFeatureMap *	gan_orthog_line_q (Gan_EdgeFeatureMap *edge_map, unsigned min_length, unsigned cut_size, float rms_error_thres, Gan_LocalFeatureMapParams *lpms, Gan_Bool copy_points, Gan_LineFeatureMap *line_map, void(*set_progress)(void *, unsigned), void *progress_obj)
	Computes image lines using an orthogonal regression algorithm.
Gan_LineFeatureMap *	gan_orthog_line_s (Gan_EdgeFeatureMap *edge_map, unsigned min_length, unsigned cut_size, float rms_error_thres, Gan_LocalFeatureMapParams *lpms, Gan_Bool copy_points, void(*set_progress)(void *, unsigned), void *progress_obj)
	Macro: Computes image lines using an orthogonal regression algorithm.
Gan_Bool	gan_segment_strings_q (Gan_EdgeFeatureMap *edge_map, unsigned test_length, float rms_error_thres, unsigned string_length_thres)
	Segments strings in an edge map.

---

Function Documentation

Gan_EdgeFeatureMap * gan_canny_edge_q (  Gan_Image *  image, Gan_Image *  mask, Gan_Mask1D *  filter_y, Gan_Mask1D *  filter_x, Gan_RGBPixel_f *  colour, Gan_Vector2_f *  direction, double  lower_thres, double  upper_thres, unsigned  string_length_thres, Gan_Matrix23_f *  A, Gan_Camera *  camera, Gan_LocalFeatureMapParams *  lpms, Gan_EdgeFeatureMap *  edge_map, void(*)(void *, unsigned)  set_progress, void *  progress_obj )

Computes edges in an image using the Canny algorithm. Parameters: image  The input image mask  Binary image indicating region to find edges or NULL filter_y  Image convolution filter in the y-direction or NULL filter_x  Image convolution filter in the x-direction or NULL colour  Colour on which to project gradients or NULL direction  Direction on which to project gradients or NULL lower_thres  Lower hysteresis threshold for string building upper_thres  Upper hysteresis threshold for string building string_length_thres  The smallest length of string allowed A  Affine transformation to apply to edgel coordinates or NULL camera  Pointer to the camera calibration or NULL lpms  Pointer to local feature map parameters or NULL edge_map  The edge map to fill with edges set_progress  Function to update progress from 1 to 100 or NULL progress_obj  Pointer passed into set_progress function or NULL Applies the Canny edge detector to find edges in the input image. The image is smoothed using the provided convolution masks. The image x/y gradients gx/gy and the RMS gradient sqrt(gx^2+gy^2) are computed. Non-maximum suppression is applied to compute the individual edge points (edgels). These are then joined into strings using a hysteresis procedure, wherein two thresholds are applied to keep weak edges so long as they are part of a string with strong edges. An affine transformation A is applied to the edgel coordinates if the A pointer is not NULL. If the camera calibration structure pointer is not NULL, distortion correction is applied to the edgel positions. camera should be the correct camera calibration for the image coordinates obtained after applying the affine transformation A. Returns: Non-NULL a pointer to the computed edge map structure, or NULL on failure. See also: gan_canny_edge_s().

Gan_EdgeFeatureMap* gan_canny_edge_s (  Gan_Image *  image, Gan_Image *  mask, Gan_Mask1D *  filter_y, Gan_Mask1D *  filter_x, Gan_RGBPixel_f *  colour, Gan_Vector2_f *  direction, double  lower_thres, double  upper_thres, unsigned  string_length_thres, Gan_Matrix23_f *  A, Gan_Camera *  camera, Gan_LocalFeatureMapParams *  lpms, void(*)(void *, unsigned)  set_progress, void *  progress_obj )

Macro: Computes edges in an image using the Canny algorithm. Parameters: image  The input image mask  Binary image indicating region to find edges or NULL filter_y  Image convolution filter in the y-direction or NULL filter_x  Image convolution filter in the x-direction or NULL colour  Colour on which to project gradients or NULL direction  Direction on which to project gradients or NULL lower_thres  Lower hysteresis threshold for string building upper_thres  Upper hysteresis threshold for string building string_length_thres  The smallest length of string allowed A  Affine transformation to apply to edgel coordinates or NULL camera  Pointer to the camera calibration or NULL lpms  Pointer to local feature map parameters or NULL set_progress  Function to update progress from 0 to 99 or NULL progress_obj  Pointer passed into set_progress function or NULL Applies the Canny edge detector to find edges in the input image. Macro call to gan_canny_edge_q(). Returns: Non-NULL a pointer to the computed edge map structure, or NULL on failure. See also: gan_canny_edge_q().

Gan_CornerFeature * gan_corner_feature_add (  Gan_CornerFeatureMap *  cmap, unsigned  r, unsigned  c, float  rf, float  cf, Gan_SquMatrix22_f *  N, int  status, int  index, float  strength )

Adds a corner to a corner feature map. Parameters: cmap  A corner feature map r  The row location of the corner in the feature map window c  The column location of the corner in the feature map window rf  The floating point row location of the corner cf  The floating point column location of the corner N  Covariance matrix of the corner position or NULL status  The status of the corner feature (user-defined) index  The index of the corner feature (user-defined) strength  The strength of the corner feature Adds a corner to a corner feature map with given coordinates, both in integer and floating corner formats, which should both be in the coordinate frame of the feature window, with (0,0) at the top-left corner. This routine transforms the floating corner coordinates appropriately given the affine transformation defined by the feature map structure cmap, removes any non-linear distortion specified by the camera part of the feature map structure, and writes all the information into a new feature point structure, a pointer to which is returned. The strength should be in units linear with the image intensity, if that is applicable. If the covariance N is passed as NULL, a default unit covariance for the corner feature is assumed. Returns: Non-NULL pointer to the new feature structure, or NULL on failure.

Gan_Bool gan_corner_feature_display (  Gan_CornerFeature *  corner, float  size, Gan_Matrix23_f *  A, Gan_RGBPixel_f *  corner_colour )

Displays a single corner feature. Parameters: corner  A corner feature size  The size of cross to draw on the display A  Affine transformation to apply to feature coordinates corner_colour  The RGB colour to display the feature Displays a single corner feature. If size is passed as zero, the corner is drawn as a point with current point size. Otherwise the corner as drawn as a cross of the given size. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_CornerFeatureMap* gan_corner_feature_map_alloc (  unsigned  max_ncorners  )

Macro: Allocates a corner feature map structure. Parameters: max_ncorners  The number of corners initially to allocate for Allocates a structure to hold corner features, and sets it to be empty. This macro calls gan_corner_feature_map_form(). Returns: non-NULL the allocated feature map, NULL on failure. See also: gan_corner_feature_map_form(), gan_corner_feature_map_free().

Gan_Bool gan_corner_feature_map_clear (  Gan_CornerFeatureMap *  cmap, unsigned  height, unsigned  width, Gan_Matrix23_f *  A, Gan_Camera *  camera, Gan_LocalFeatureMapParams *  lpms )

Sets up and clears a corner feature map structure. Parameters: cmap  A corner feature map height  The height of the feature map region width  The width of the feature map region A  Affine transformation from window to corner coords or NULL camera  A pointer to the camera calibration or NULL lpms  Local feature map parameters or NULL Sets attributes of a corner feature map prior to filling the feature map with corners. The lpms argument, if not NULL, is passed to gan_local_feature_map_form() to build a local blocked feature map for the corner features. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_Bool gan_corner_feature_map_display (  Gan_CornerFeatureMap *  cmap, float  size, Gan_Matrix23_f *  A, Gan_RGBPixel_f *  corner_colour, Gan_RGBPixel_f *  bbox_colour )

Displays a corner feature map. Parameters: cmap  The corner feature map size  The size of cross to draw on the display A  Affine transformation to apply to feature coordinates corner_colour  The colour to display the features bbox_colour  The colour to display the bounding box Displays a corner feature map. If size is passed as zero, the corner is drawn as a point with current point size. Otherwise the corner as drawn as a cross of the given size. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_CornerFeatureMap * gan_corner_feature_map_form (  Gan_CornerFeatureMap *  cmap, unsigned  max_ncorners )

Forms a corner feature map structure. Parameters: cmap  A corner feature map max_ncorners  The number of corners initially to allocate for Fills a structure to hold corner features, and sets it to be empty. Returns: non-NULL the formed feature map cmap, or NULL on failure. See also: gan_corner_feature_map_alloc(), gan_corner_feature_map_free().

void gan_corner_feature_map_free (  Gan_CornerFeatureMap *  cmap  )

Frees a corner feature map structure. Parameters: cmap  A corner feature map Frees a previously formed/allocated structure that holds corner features. Returns: No value. See also: gan_corner_feature_map_form(), gan_corner_feature_map_alloc().

Gan_Bool gan_corner_feature_map_postprocess (  Gan_CornerFeatureMap *  cmap  )

Postprocess feature map. Parameters: cmap  A corner feature map Postprocess feature map, building index array into local feature map. Call this function after building local feature counts with gan_corner_feature_add() using a UINT_MAX index argument, so that the index array for the local features will be built. Returns: GAN_TRUE on success, GAN_FALSE on failure. See also: gan_corner_feature_add().

Gan_EdgeFeature * gan_edge_feature_add (  Gan_EdgeFeatureMap *  emap, unsigned  r, unsigned  c, float  rf, float  cf, float  angle, float  cov, int  status, int  index, float  strength )

Adds an edge to an edge feature map. Parameters: emap  An edge feature map r  The row location of the edge in the feature map window c  The column location of the edge in the feature map window rf  The floating edge row location of the edge cf  The floating edge column location of the edge angle  The orientation of the edge "normal" cov  The covariance of the edge position in the normal direction status  The status of the edge feature (user-defined) index  The index of the edge feature (user-defined) strength  The strength of the edge feature Adds an edge to an edge feature map with given coordinates, both in integer and floating edge formats, which should both be in the coordinate frame of the feature window, with (0,0) at the top-left corner. This routine transforms the floating edge coordinates appropriately given the affine transformation defined by the feature map structure emap, removes any non-linear distortion specified by the camera part of the feature map structure, and writes all the information into a new feature edge structure, a pointer to which is returned. The strength should be in units linear with the image intensity, if that is applicable. Returns: Non-NULL pointer to the new feature structure, or NULL on failure.

Gan_Bool gan_edge_feature_display (  Gan_EdgeFeature *  edge, float  size, Gan_Matrix23_f *  A, Gan_RGBPixel_f *  edge_colour )

Displays a single edge feature. Parameters: edge  A edge feature size  The size of cross to draw on the display A  Affine transformation to apply to feature coordinates edge_colour  The colour to display the feature Displays a single edge feature. If size is passed as zero, the edge is drawn as a point with current point size. Otherwise the edge as drawn as a cross of the given size. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_EdgeFeatureMap* gan_edge_feature_map_alloc (  unsigned  max_nedges, unsigned  max_nstrings )

Macro: Allocates a edge feature map structure. Parameters: max_nedges  The number of edges initially to allocate for max_nstrings  The number of strings initially to allocate for Allocates a structure to hold edge features, and sets it to be empty. This macro calls gan_edge_feature_map_form(). Returns: non-NULL the allocated feature map, or NULL on failure. See also: gan_edge_feature_map_form(), gan_edge_feature_map_free().

Gan_Bool gan_edge_feature_map_clear (  Gan_EdgeFeatureMap *  emap, unsigned  height, unsigned  width, Gan_Matrix23_f *  A, Gan_Camera *  camera, Gan_LocalFeatureMapParams *  lpms )

Sets up and clears an edge feature map structure. Parameters: emap  An edge feature map height  The height of the feature map region width  The width of the feature map region A  Affine transformation from window to edge coords or NULL camera  A pointer to the camera calibration or NULL lpms  Local feature map parameters or NULL Sets attributes of an edge feature map prior to filling the feature map with edges. The lpms argument, if not NULL, is passed to gan_local_feature_map_form() to build a local blocked feature map for the edge features. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_Bool gan_edge_feature_map_display (  Gan_EdgeFeatureMap *  emap, float  size, Gan_Matrix23_f *  A, Gan_RGBPixel_f *  edge_colour, Gan_RGBPixel_f *  string_colour, Gan_RGBPixel_f *  first_colour, Gan_RGBPixel_f *  last_colour, Gan_RGBPixel_f *  bbox_colour )

Displays a edge feature map. Parameters: emap  The edge feature map size  The size of cross to draw on the display A  Affine transformation to apply to feature coordinates edge_colour  The colour to display the features string_colour  The colour to display any strings first_colour  The colour to display the start of a string last_colour  The colour to display the end of a string bbox_colour  The colour to display the bounding box Displays a edge feature map. If size is passed as zero, the edge is drawn as a point with current point size. Otherwise the edge as drawn as a cross of the given size. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_EdgeFeatureMap * gan_edge_feature_map_form (  Gan_EdgeFeatureMap *  emap, unsigned  max_nedges, unsigned  max_strings )

Forms an edge feature map structure. Parameters: emap  an edge feature map max_nedges  The number of edges initially to allocate for max_nstrings  The number of strings initially to allocate for Fills a structure to hold edge features, and sets it to be empty. Returns: non-NULL the formed feature map emap, or NULL on failure. See also: gan_edge_feature_map_alloc(), gan_edge_feature_map_free().

void gan_edge_feature_map_free (  Gan_EdgeFeatureMap *  emap  )

Frees an edge feature map structure. Parameters: emap  an edge feature map Frees a previously formed/allocated structure that holds edge features. Returns: No value. See also: gan_edge_feature_map_form(), gan_edge_feature_map_alloc().

Gan_Bool gan_edge_feature_map_postprocess (  Gan_EdgeFeatureMap *  emap  )

Postprocess feature map. Parameters: emap  an edge feature map Postprocess feature map, building index array into local feature map. Call this function after building local feature counts with gan_edge_feature_add() using a UINT_MAX index argument, so that the index array for the local features will be built. Returns: GAN_TRUE on success, GAN_FALSE on failure. See also: gan_edge_feature_add().

Gan_EdgeString * gan_edge_feature_string_add (  Gan_EdgeFeatureMap *  emap, Gan_EdgeFeature *  edge )

Adds an edge string to an edge feature map. Parameters: emap  an edge feature map edge  The first edge in the edge string Adds a new edge string to an edge feature map, starting with the given edge. Returns: Non-NULL pointer to the new feature string structure, or NULL on failure.

Gan_Bool gan_edge_feature_string_set_status (  Gan_EdgeString *  string, int  status )

Sets the status of all edges in the string. Parameters: string  an edge feature string status  A status value Sets the status of all edges in the string to the given status value. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_CornerFeatureMap * gan_harris_corner_q (  Gan_Image *  image, Gan_Image *  mask, Gan_Mask1D *  image_filter_y, Gan_Mask1D *  image_filter_x, Gan_Mask1D *  grad_filter_y, Gan_Mask1D *  grad_filter_x, float  kappa, float  thres, Gan_Matrix23_f *  A, int  status, Gan_Camera *  camera, Gan_LocalFeatureMapParams *  lpms, Gan_CornerFeatureMap *  corner_map )

Computes corners in an image using the Harris algorithm. Parameters: image  The input image mask  Binary image indicating region to find corners or NULL image_filter_y  The image convolution mask in the y-direction image_filter_x  The image convolution mask in the x-direction grad_filter_y  The gradient convolution mask in the y-direction grad_filter_x  The gradient convolution mask in the x-direction kappa  The weighting factor used to compute the corner strength thres  The threshold on corner strength A  Affine transformation to apply to corner coordinates or NULL status  The initial status value set for each corner camera  Pointer to the camera calibration or NULL lpms  Pointer to local feature map parameters or NULL corner_map  The corner map to fill with corners Applies the Harris corner detector to find corners in the input image. The squared image x/y gradients gx2/gy2 and product of x & y gradients gxy are computed. These are convolved with the given convolution masks grad_filter_y and grad_filter_x in the y/x directions respectively. The smoothed gradients sgx2, sgy2 and sgxy are then combined pixel-by-pixel into a corner strength using the provided weighting factor kappa. The strength is non-maximum suppressed and thresholded by the given value thres. An extra feature (from Forster's corner detector) is a pre-smoothing of the image given by the image_filter_y and image_filter_x convolution masks. An affine transformation A is applied to the corner coordinates if the A pointer is not NULL. If the camera calibration structure pointer is not NULL, distortion correction is applied to the corner positions. camera should be the correct camera calibration for the image coordinates obtained after applying the affine transformation A. Returns: Non-NULL a pointer to the computed corner map structure, or NULL on failure. See also: gan_harris_corner_s().

Gan_CornerFeatureMap* gan_harris_corner_s (  Gan_Image *  image, Gan_Image *  mask, Gan_Mask1D *  image_filter_y, Gan_Mask1D *  image_filter_x, Gan_Mask1D *  grad_filter_y, Gan_Mask1D *  grad_filter_x, float  kappa, float  thres, Gan_Matrix23_f *  A, int  status, Gan_Camera *  camera, Gan_LocalFeatureMapParams *  lpms )

Macro: Computes corners in an image using the Harris algorithm. Parameters: image  The input image mask  Binary image indicating region to find corners or NULL image_filter_y  The image convolution mask in the y-direction image_filter_x  The image convolution mask in the x-direction grad_filter_y  The gradient convolution mask in the y-direction grad_filter_x  The gradient convolution mask in the x-direction kappa  The weighting factor used to compute the corner strength thres  The threshold on corner strength A  Affine transformation to apply to corner coordinates or NULL status  The initial status value set for each corner camera  Pointer to the camera calibration or NULL lpms  Pointer to local feature map parameters or NULL Applies the Harris corner detector to find corners in the input image. Macro call to gan_harris_corner_q(). Returns: Non-NULL a pointer to the computed corner map structure, or NULL on failure. See also: gan_harris_corner_q().

Gan_LineFeature * gan_line_feature_add (  Gan_LineFeatureMap *  lmap, float  y1, float  x1, float  y2, float  x2, Gan_SquMatrix22_f *  N, int  status, int  index, float  strength, Gan_Vector2_f *  point, unsigned  npoints )

Adds a line to a line feature map. Parameters: lmap  A line feature map y1  The row location of the first line endpoint x1  The column location of the first line endpoint y2  The row location of the second line endpoint x2  The column location of the second line endpoint N  Covariance of canonical line parameters status  The status of the line feature (user-defined) index  The index of the line feature (user-defined) strength  The strength of the line feature point  Array of points or NULL npoints  Number of points in array or zero (if point is NULL) Adds a line to a line feature map with given coordinates, both in integer and floating line formats, which should both be in the coordinate frame of the feature window, with (0,0) at the top-left corner. This routine transforms the floating line coordinates appropriately given the affine transformation defined by the feature map structure lmap, removes any non-linear distortion specified by the camera part of the feature map structure, and writes all the information into a new feature line structure, a lineer to which is returned. The strength should be in units linear with the image intensity, if that is applicable. N is the covariance of the canonical line parameters a/b in y=ax+b, with the x/y coordinate system centred on the midpoint of the line (p1+p2)/2, with the positive x-axis along the line towards the p2 endpoint, and the positive y-axis 90 degrees anticlockwise from the x-axis. Returns: Non-NULL pointer to the new feature structure, or NULL on failure.

Gan_Bool gan_line_feature_display (  Gan_LineFeature *  line, float  line_thickness, Gan_Matrix23_f *  A, Gan_RGBPixel_f *  line_colour, Gan_RGBPixel_f *  first_colour, Gan_RGBPixel_f *  last_colour, Gan_RGBPixel_f *  point_colour )

Displays a single line feature. Parameters: line  A line feature line_thickness  Thickness of lines to render A  Affine transformation to apply to feature coordinates line_colour  The colour to display the line feature first_colour  The colour to highlight the first line endpoint last_colour  The colour to highlight the second line endpoint point_colour  The colour to display points, where applicable, or NULL if you don't want to display them Returns: GAN_TRUE on success, GAN_FALSE on failure. Displays a single line feature.

Gan_LineFeatureMap* gan_line_feature_map_alloc (  unsigned  max_nlines  )

Macro: Allocates a line feature map structure. Parameters: max_nlines  The number of lines initially to allocate for Allocates a structure to hold line features, and sets it to be empty. This macro calls gan_line_feature_map_form(). Returns: non-NULL the allocated feature map, or NULL on failure. See also: gan_line_feature_map_form(), gan_line_feature_map_free().

Gan_Bool gan_line_feature_map_clear (  Gan_LineFeatureMap *  lmap, unsigned  height, unsigned  width, Gan_Matrix23_f *  A, Gan_LocalFeatureMapParams *  lpms )

Sets up and clears a line feature map structure. Parameters: lmap  A line feature map height  The height of the feature map region width  The width of the feature map region A  Affine transformation from window to line coords or NULL lpms  Local feature map parameters or NULL Sets attributes of a line feature map prior to filling the feature map with lines. The lpms argument, if not NULL, is passed to gan_local_feature_map_form() to build a local blocked feature map for the line features. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_LineFeatureMap * gan_line_feature_map_copy (  Gan_LineFeatureMap *  lmap  )

Copies a line feature map structure. Parameters: lmap  Input line feature map Returns: Copy of input structure or NULL on error Copies a structure that holds line features. See also: gan_line_feature_map_form(), gan_line_feature_map_alloc().

Gan_Bool gan_line_feature_map_display (  Gan_LineFeatureMap *  lmap, float  line_thickness, Gan_Matrix23_f *  A, Gan_RGBPixel_f *  line_colour, Gan_RGBPixel_f *  first_colour, Gan_RGBPixel_f *  last_colour, Gan_RGBPixel_f *  point_colour, Gan_RGBPixel_f *  bbox_colour )

Displays a line feature map. Parameters: lmap  The line feature map line_thickness  Thickness of lines to render A  Affine transformation to apply to feature coordinates line_colour  The colour to display the line features first_colour  The colour to highlight the first line endpoint last_colour  The colour to highlight the second line endpoint point_colour  The colour to display points, where applicable, or NULL if you don't want to display them bbox_colour  The colour to display the bounding box Returns: GAN_TRUE on success, GAN_FALSE on failure. Displays a line feature map.

Gan_LineFeatureMap * gan_line_feature_map_form (  Gan_LineFeatureMap *  lmap, unsigned  max_nlines )

Forms a line feature map structure. Parameters: lmap  A line feature map max_nlines  The number of lines initially to allocate for Fills a structure to hold line features, and sets it to be empty. Returns: non-NULL The formed feature map lmap, or NULL on failure. See also: gan_line_feature_map_alloc(), gan_line_feature_map_free().

void gan_line_feature_map_free (  Gan_LineFeatureMap *  lmap  )

Frees a line feature map structure. Parameters: lmap  A line feature map Frees a previously formed/allocated structure that holds line features. Returns: No value. See also: gan_line_feature_map_form(), gan_line_feature_map_alloc().

Gan_Bool gan_line_feature_map_postprocess (  Gan_LineFeatureMap *  lmap  )

Postprocess feature map. Parameters: lmap  A line feature map Postprocess feature map, building index array into local feature map. Call this function after building local feature counts with gan_line_feature_add() using a UINT_MAX index argument, so that the index array for the local features will be built. Returns: GAN_TRUE on success, or GAN_FALSE on failure. See also: gan_line_feature_add().

Gan_Bool gan_local_feature_line_add (  Gan_LocalFeatureMap *  pmap, unsigned  r1, unsigned  c1, unsigned  r2, unsigned  c2, unsigned  index )

Adds a line feature to a local feature map. Parameters: pmap  The local feature map r1  Row position of first endpoint of the feature c1  Column position of first endpoing of the feature r2  Row position of second endpoint of the feature c2  Column position of second endpoing of the feature index  Index of the feature in the feature map referenced Adds a line feature at endpoint positions (r1,c1) and (r2,c2) to the given local feature map. If index is UINT_MAX, the index is ignored; otherwise it is added to the index array stored in the local feature map. Returns: GAN_TRUE on success, GAN_FALSE on failure. See also: gan_local_feature_point_add().

Gan_LocalFeatureMap* gan_local_feature_map_alloc (  unsigned  height, unsigned  width, Gan_LocalFeatureMapParams *  pms )

Macro: Allocates a local feature map structure. Parameters: height  The vertical size of the local feature map width  The vertical size of the local feature map pms  Pointer to a structure holding other parameters Allocates a structure to hold a local blocked representation of indices of features stored in a separate feature map (e.g. a point/edge/line feature map), and sets it to be empty. The pms structure contains the vertical/horizontal offsets between blocks, and the "catchment area" or size of each block. This macro calls gan_local_feature_map_form(). Returns: non-NULL the allocated local feature map, NULL on failure. See also: gan_local_feature_map_form(), gan_local_feature_map_free().

Gan_Bool gan_local_feature_map_clear (  Gan_LocalFeatureMap *  pmap, unsigned  height, unsigned  width, Gan_LocalFeatureMapParams *  pms )

Clears a local feature map structure. Parameters: pmap  The local feature map height  The vertical size of the local feature map width  The vertical size of the local feature map pms  Pointer to a structure holding other parameters or NULL Clears all the stored indices from an existing local feature map, and resets the dimensions of the feature map according to the provided arguments. Returns: GAN_TRUE on success, GAN_FALSE on failure. See also: gan_local_feature_map_form(), gan_local_feature_map_free().

Gan_Bool gan_local_feature_map_find_block (  Gan_LocalFeatureMap *  pmap, double  y, double  x, Gan_Matrix23 *  Ai, unsigned *  cr, unsigned *  cc )

Computes the block a feature position lies in. Parameters: pmap  The local feature map y  The vertical feature position x  The horizontal feature position Ai  The transformation from x,y coords. into local feature map cr  Pointer to the resulting local feature map row cc  Pointer to the resulting local feature map column Given coordinates x,y for a feature, and a transformation Ai to get back to the coordinates of the local feature map, returns the block row/column in the cr & cc pointers. Returns: GAN_TRUE on success, GAN_FALSE on failure.

Gan_LocalFeatureMap * gan_local_feature_map_form (  Gan_LocalFeatureMap *  pmap, unsigned  height, unsigned  width, Gan_LocalFeatureMapParams *  pms )

Forms a local feature map structure. Parameters: pmap  The local feature map to form height  The vertical size of the local feature map width  The vertical size of the local feature map pms  Pointer to a structure holding other parameters or NULL Forms a structure to hold a local blocked representation of indices of features stored in a separate feature map (e.g. a point/edge/line feature map), and sets it to be empty. The pms structure contains the vertical/horizontal offsets between blocks, and the "catchment area" or size of each block. Returns: non-NULL the formed local feature map, or NULL on failure. See also: gan_local_feature_map_form(), gan_local_feature_map_free().

void gan_local_feature_map_free (  Gan_LocalFeatureMap *  pmap  )

Frees a local feature map structure. Parameters: pmap  The local feature map to free Frees a structure holding a local blocked representation of indices of features. Returns: No value See also: gan_local_feature_map_form(), gan_local_feature_map_alloc().

Gan_Bool gan_local_feature_map_set_indices (  Gan_LocalFeatureMap *  pmap  )

Sets indices for a local feature map. Parameters: pmap  The local feature map Having called gan_local_feature_point_add() and/or gan_local_feature_line_add() to count the features in the local feature map, this function allocates and builds the array of indices for those features. It doesn't fill the array with values, however. This is done by calling gan_local_feature_point_add() and/or gan_local_feature_line_add() again for each point/line feature with the correct index argument. Returns: GAN_TRUE on success, GAN_FALSE on failure. See also: gan_local_feature_point_add().

Gan_Bool gan_local_feature_point_add (  Gan_LocalFeatureMap *  pmap, unsigned  r, unsigned  c, unsigned  index )

Adds a point feature to a local feature map. Parameters: pmap  The local feature map r  Row position of the feature c  Column position of the feature index  Index of the feature in the feature map referenced Adds a point feature at position (r,c) to the given local feature map. If index is UINT_MAX, the index is ignored; otherwise it is added to the index array stored in the local feature map. Returns: GAN_TRUE on success, GAN_FALSE on failure. See also: gan_local_feature_line_add().

Gan_LineFeatureMap * gan_orthog_line_q (  Gan_EdgeFeatureMap *  edge_map, unsigned  min_length, unsigned  cut_size, float  rms_error_thres, Gan_LocalFeatureMapParams *  lpms, Gan_Bool  copy_points, Gan_LineFeatureMap *  line_map, void(*)(void *, unsigned)  set_progress, void *  progress_obj )

Computes image lines using an orthogonal regression algorithm. Parameters: edge_map  The input edge map min_length  The minimum line length cut_size  The length to cut off the ends of each line rms_error_thres  Threshold on RMS error of line fit lpms  Pointer to local feature map parameters or NULL copy_points  Whether to copy the fitted edge points into a line line_map  Resulting line map set_progress  Function to update progress from 1 to 100 or NULL progress_obj  Pointer passed into set_proogress function or NULL Applies a recursive orthogonal regression line finder to edges found in an image. Returns: Non-NULL a pointer to the computed line map structure, or NULL on failure. See also: gan_orthog_line_s().

Gan_LineFeatureMap* gan_orthog_line_s (  Gan_EdgeFeatureMap *  edge_map, unsigned  min_length, unsigned  cut_size, float  rms_error_thres, Gan_LocalFeatureMapParams *  lpms, Gan_Bool  copy_points, void(*)(void *, unsigned)  set_progress, void *  progress_obj )

Macro: Computes image lines using an orthogonal regression algorithm. Parameters: edge_map  The input edge map min_length  The minimum line length cut_size  The length to cut off the ends of each line rms_error_thres  Threshold on RMS error of line fit lpms  Pointer to local feature map parameters or NULL copy_points  Whether to copy the fitted edge points into a line set_progress  Function to update progress from 0 to 99 or NULL progress_obj  Pointer passed into set_progress function or NULL Applies a recursive orthogonal regression line finder to edges found in an image. Macro call to gan_orthog_line_q(). Returns: Non-NULL a pointer to the computed line map structure, or NULL on failure. See also: gan_orthog_line_q().

Gan_Bool gan_segment_strings_q (  Gan_EdgeFeatureMap *  edge_map, unsigned  test_length, float  rms_error_thres, unsigned  string_length_thres )

Segments strings in an edge map. Parameters: edge_map  The input edge map test_length  The length of local strings to test rms_error_thres  Threshold on RMS error of a local line fit string_length_thres  The smallest length of string allowed Returns: GAN_TRUE on success, GAN_FALSE on failure. Segments strings in an edge map by applying a local line fit along the string, splitting it where the error residual is above the given threshold. The parameter test_length must be odd and >= 3.

---