Definitions for the image block surface detector. More...

#include <jwsc/config.h>
#include <stdlib.h>
#include <stdio.h>
#include <inttypes.h>
#include <assert.h>
#include <math.h>
#include <string.h>
#include <errno.h>
#include "jwsc/base/error.h"
#include "jwsc/vector/vector.h"
#include "jwsc/vector/vector_math.h"
#include "jwsc/matblock/matblock.h"
#include "jwsc/matblock/matblock_fft.h"
#include "jwsc/matblock/matblock_conv.h"
#include "jwsc/filter/3d.h"
#include "jwsc/prob/pmf.h"
#include "jwsc/imgblock/surface.h"

Include dependency graph for surface.c:

Go to the source code of this file.

Data Structures
struct	Gradient_f
	Gradient element detected using the partial derivative masks. More...
Defines
#define	INV_SQRT_2 0.70710678
	Estimate of 1 / sqrt(2).
#define	INV_SQRT_3 0.57735027
	Estimate of 1 / sqrt(3).
Functions
static Error *	create_gradient_map_f (Gradient_f ***map_out, const Matblock_f m, float sigma, float grad_mat_weight, float grad_row_weight, float grad_col_weight)
	Creates a gradient map from a matrix.
static Gradient_f *	follow_gradient_f (int32_t grad_mat_in_out, int32_t grad_row_in_out, int32_t grad_col_in_out, float dir_x, float dir_y, float dir_z, Gradient_f **map, uint32_t num_mats, uint32_t num_rows, uint32_t num_cols)
	Get the next gradient along the specified gradient.
static Gradient_f *	get_maximal_along_gradient_f (int32_t grad_mat_in_out, int32_t grad_row_in_out, int32_t grad_col_in_out, Gradient_f **map, uint32_t num_mats, uint32_t num_rows, uint32_t num_cols)
	Non-maximal suppression.
static void	follow_surface_f (Gradient_f grad, int32_t grad_mat, int32_t grad_row, int32_t grad_col, Gradient_f **map, uint32_t num_mats, uint32_t num_rows, uint32_t num_cols, float end_thresh)
	Hysterisis on the surface.
static void	get_surface_points_from_gradient_map_f (Surface_point_f *pts_out, uint32_t num_pts_out, const Matblock_f m, Gradient_f **map, uint32_t num_mats, uint32_t num_rows, uint32_t num_cols, float begin_thresh, float end_thresh)
	Uses non-maximal suppression and hysterisis to get the surface points from the image block.
detect_imgblock_surface_points
Detects surface points in each sample of an image block.
Error *	detect_imgblock_surface_points_f (Surface_point_f *r_pts_out, uint32_t num_r_pts_out, Surface_point_f *g_pts_out, uint32_t num_g_pts_out, Surface_point_f *b_pts_out, uint32_t num_b_pts_out, const Imgblock_f *img, float sigma, float grad_img_weight, float grad_row_weight, float grad_col_weight, float begin_thresh, float end_thresh)
	Detects surface points in each sample of a single precision image block.
detect_matblock_surface_points
Detects surface points in a matrix block (single-sample image block).
Error *	detect_matblock_surface_points_f (Surface_point_f *pts_out, uint32_t num_pts_out, const Matblock_f *m, float sigma, float grad_mat_weight, float grad_row_weight, float grad_col_weight, float begin_thresh, float end_thresh)
	Detects surface points in a single precision matrix block (single-sample image block).
sample_surface_points
Randomly samples surface points from an array of them.
void	sample_surface_points_f (Surface_point_f *pts_out, uint32_t num_pts_out, const Surface_point_f *pts_in, uint32_t num_pts_in, float p)
	Randomly samples single precision surface points from an array of them.
color_surface_points
Colors surface points in an image block.
void	color_surface_points_f (Imgblock_f *img_out, const Imgblock_f img_in, const Surface_point_f pts, uint32_t num_pts, const Pixel_f pxl)
	Colors single precision surface points in an image block.
read_surface_points
Reads an array of surface points in ASCII format from a file.
Error *	read_surface_points_f (Surface_point_f *pts_out, uint32_t num_pts_out, const char *fname)
	Reads an array of single precision surface points in ASCII format from a file.
write_surface_points
Writes an array of surface points in ASCII format to a file.
Error *	write_surface_points_f (const Surface_point_f pts, uint32_t num_pts, const char fname)
	Writes an array of single precision surface pionts in ASCII format to a file.
create_surface_patch
Creates a Surface_patch from a Surface_point.
void	create_surface_patch_f (Surface_patch_f *patch_out, const Surface_point_f point, float size, float x_scale, float y_scale, float z_scale)
	Creates a Surface_patch_f from a Surface_point_f.
free_surface_patch
Frees a Surface_patch from a Surface_point.
void	free_surface_patch_f (Surface_patch_f *patch)
	Frees a Surface_patch_f.

Detailed Description

Definitions for the image block surface detector.

Author:: Joseph Schlecht

License:: Creative Commons BY-NC-SA 3.0

The surface detection algorithm is a variation of the standard Canny algorithm: the image block is convolved with the gradiant of Gaussian, then non-maximal suppression and hysterisis are applied to the resulting gradient map.

Definition in file surface.c.

Define Documentation

#define INV_SQRT_2 0.70710678

Estimate of 1 / sqrt(2).

Definition at line 77 of file surface.c.

#define INV_SQRT_3 0.57735027

Estimate of 1 / sqrt(3).

Definition at line 81 of file surface.c.

Function Documentation

static Error* create_gradient_map_f	(	Gradient_f ****	map_out,
		const Matblock_f *	m,
		float	sigma,
		float	grad_mat_weight,
		float	grad_row_weight,
		float	grad_col_weight
	)		`[static]`

Creates a gradient map from a matrix.

Definition at line 112 of file surface.c.

static Gradient_f* follow_gradient_f	(	int32_t *	grad_mat_in_out,
		int32_t *	grad_row_in_out,
		int32_t *	grad_col_in_out,
		float	dir_x,
		float	dir_y,
		float	dir_z,
		Gradient_f ***	map,
		uint32_t	num_mats,
		uint32_t	num_rows,
		uint32_t	num_cols
	)		`[static]`

Get the next gradient along the specified gradient.

Definition at line 245 of file surface.c.

static Gradient_f* get_maximal_along_gradient_f	(	int32_t *	grad_mat_in_out,
		int32_t *	grad_row_in_out,
		int32_t *	grad_col_in_out,
		Gradient_f ***	map,
		uint32_t	num_mats,
		uint32_t	num_rows,
		uint32_t	num_cols
	)		`[static]`

Non-maximal suppression.

Definition at line 337 of file surface.c.

static void follow_surface_f	(	Gradient_f *	grad,
		int32_t	grad_mat,
		int32_t	grad_row,
		int32_t	grad_col,
		Gradient_f ***	map,
		uint32_t	num_mats,
		uint32_t	num_rows,
		uint32_t	num_cols,
		float	end_thresh
	)		`[static]`

Hysterisis on the surface.

Recursively follows the surface in the direction of 8 vectors orthogonal to the surface gradient vector grad.

Definition at line 438 of file surface.c.

static void get_surface_points_from_gradient_map_f	(	Surface_point_f **	pts_out,
		uint32_t *	num_pts_out,
		const Matblock_f *	m,
		Gradient_f ***	map,
		uint32_t	num_mats,
		uint32_t	num_rows,
		uint32_t	num_cols,
		float	begin_thresh,
		float	end_thresh
	)		`[static]`

Uses non-maximal suppression and hysterisis to get the surface points from the image block.

The last six parameters are to counter-act any buffering that was done.

Definition at line 525 of file surface.c.

Error* detect_imgblock_surface_points_f	(	Surface_point_f **	r_pts_out,
		uint32_t *	num_r_pts_out,
		Surface_point_f **	g_pts_out,
		uint32_t *	num_g_pts_out,
		Surface_point_f **	b_pts_out,
		uint32_t *	num_b_pts_out,
		const Imgblock_f *	img,
		float	sigma,
		float	grad_img_weight,
		float	grad_row_weight,
		float	grad_col_weight,
		float	begin_thresh,
		float	end_thresh
	)

Detects surface points in each sample of a single precision image block.

Smoothed partial derivative kernels, non-maximal suppression, and hysteresis are used to trace out the surface points from the input image block.

Parameters:

r_pts_out	Result parameter. If *r_pts_out is NULL, an array of surface points is allocated; otherwise its space is re-used.
num_r_pts_out	Result parameter. Number of surface points detected in the red sample.
g_pts_out	Result parameter. If *g_pts_out is NULL, an array of surface points is allocated; otherwise its space is re-used.
num_g_pts_out	Result parameter. Number of surface points detected in the green sample.
b_pts_out	Result parameter. If *b_pts_out is NULL, an array of surface points is allocated; otherwise its space is re-used.
num_b_pts_out	Result parameter. Number of surface points detected in the blue sample.
img	Image block to get the surface points of.
sigma	Parameter for the Gaussian kernel used for smoothing and surface detection.
grad_img_weight	Gradient weight for the image component.
grad_row_weight	Gradient weight for the row component.
grad_col_weight	Gradient weight for the column component.
begin_thresh	Used when scanning the image block to look for gradient magnitudes to follow under non-maximal suppression.
end_thresh	Once a surface is found under non-maximal suppression, it is followed (perpendicular to the gradient) until the gradient magnitude falls below this threshold.

Returns:

On success, NULL is returned. On error, an Error is returned and *[rgb]_pts_out are freed and set to NULL.

ERROR_INV_ARG Sigma is too small.

Definition at line 673 of file surface.c.

Error* detect_matblock_surface_points_f	(	Surface_point_f **	pts_out,
		uint32_t *	num_pts_out,
		const Matblock_f *	m,
		float	sigma,
		float	grad_mat_weight,
		float	grad_row_weight,
		float	grad_col_weight,
		float	begin_thresh,
		float	end_thresh
	)

Detects surface points in a single precision matrix block (single-sample image block).

Smoothed partial derivative kernels, non-maximal suppression, and hysteresis are used to trace out the surface points from the input image block.

Parameters:

pts_out	Result parameter. If *pts_out is NULL, an array of surface points is allocated; otherwise its space is re-used.
num_pts_out	Result parameter. Number of surface points detected.
m	Matrix block to get the surface points of.
sigma	Parameter for the Gaussian kernel used for smoothing and surface detection.
grad_mat_weight	Gradient weight for the matrix component.
grad_row_weight	Gradient weight for the row component.
grad_col_weight	Gradient weight for the column component.
begin_thresh	Used when scanning the image block to look for gradient magnitudes to follow under non-maximal suppression.
end_thresh	Once an surface is found under non-maximal suppression, it is followed (perpendicular to the gradient) until the gradient magnitude falls below this threshold.

Returns:

On success, NULL is returned. On error, an Error is returned and *pts_out are freed and set to NULL.

ERROR_INV_ARG Sigma is too small.

Definition at line 761 of file surface.c.

void sample_surface_points_f	(	Surface_point_f **	pts_out,
		uint32_t *	num_pts_out,
		const Surface_point_f *	pts_in,
		uint32_t	num_pts_in,
		float	p
	)

Randomly samples single precision surface points from an array of them.

Parameters:

pts_out	Result parameter. If *pts_out is NULL, an array of surface points is allocated; otherwise its space is re-used.
num_pts_out	Number of surface points sampled.
pts_in	Array of surface points to sample from.
num_pts_in	Number of surface points in pts_in.
p	Bernoulli parameter; probability of sampling an surface point.

Note:: If *pts_out == pts_in, then pts_in is overwritten.

Definition at line 818 of file surface.c.

void color_surface_points_f	(	Imgblock_f **	img_out,
		const Imgblock_f *	img_in,
		const Surface_point_f *	pts,
		uint32_t	num_pts,
		const Pixel_f *	pxl
	)

Colors single precision surface points in an image block.

Parameters:

img_out	Result parameter. If *img_out is NULL, an image block is allocated; otherwise its space is re-used.
img_in	Image block to color the edge points on.
pts	Surface points to use.
num_pts	Number of elements in pts.
pxl	Pixel to use for coloring the surface points.

Definition at line 879 of file surface.c.

Error* read_surface_points_f	(	Surface_point_f **	pts_out,
		uint32_t *	num_pts_out,
		const char *	fname
	)

Reads an array of single precision surface points in ASCII format from a file.

The first line of the file must contain the number of surface points and each line after that must contain the parameters for one of those points. For example:

 num_pts=3
 col=0 row=0 mat=0 dcol=1 drow=1 dmat=2 intensity=1
 col=9 row=8 mat=7 dcol=4 drow=1 dmat=3 intensity=1
 col=1 row=2 mat=3 dcol=2 drow=1 dmat=0 intensity=1

Parameters:

pts_out	Result parameter. If *pts_out is NULL, an array of surface points is allocated; otherwise its space is re-used.
num_pts_out	Number of surface points read from the file.
fname	Name of the file to read from.

Returns:

On success, NULL is returned. On error, an Error is returned and *pts_out is freed and set to NULL.

ERROR_INV_ARG The file to read from is not formatted properly.
ERROR_IO Could not read from fname.

Definition at line 937 of file surface.c.

Error* write_surface_points_f	(	const Surface_point_f *	pts,
		uint32_t	num_pts,
		const char *	fname
	)

Writes an array of single precision surface pionts in ASCII format to a file.

The first line of the file contains the number of surface points and each line after that contains the parameters for one of those points. For example:

 num_pts=3
 col=0 row=0 mat=0 dcol=1 drow=1 dmat=2 intensity=1
 col=9 row=8 mat=7 dcol=4 drow=1 dmat=3 intensity=1
 col=1 row=2 mat=3 dcol=2 drow=1 dmat=0 intensity=1

Parameters:

pts	Array of surface points to write.
num_pts	Number of surface points write to the file.
fname	Name of the file to write to.

Returns:

On success, NULL is returned. On error, an Error is returned.

ERROR_IO Could not read from fname.

Definition at line 1023 of file surface.c.

void create_surface_patch_f	(	Surface_patch_f **	patch_out,
		const Surface_point_f *	point,
		float	size,
		float	x_scale,
		float	y_scale,
		float	z_scale
	)

Creates a Surface_patch_f from a Surface_point_f.

Parameters:

patch_out	Result parameter.
point	Point to create a patch from.
size	Length of each side of the patch.
x_scale	Number of world units per column value in a surface point.
y_scale	Number of world units per row value in a surface point.
z_scale	Number of world units per image value in a surface point.

Creates square shaped patches with each side of length size.

Definition at line 1081 of file surface.c.

void free_surface_patch_f ( Surface_patch_f * patch )

Frees a Surface_patch_f.

Parameters:

patch Surface_patch_f to free.

Definition at line 1211 of file surface.c.

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation