Segmentation.h File Reference

hello Segmentation header. More...

#include "SimplePixelImage.h"
#include "MedianFilter.h"
#include "AllocMem.h"

Go to the source code of this file.

Classes

struct _FilesOptions

Files information: paths, names and saving options. More...

struct _OutputOptions

Holds all options on which where and how data should be output. More...

struct _PointDouble

Position of a pixel in double format. More...

struct _SegmentationOptions

Possible options of image segmentation. More...

struct _SegmentationParameters

Parameters used in the segmentation algorithm. More...

struct _SpotStatistics

Characteristic properties of a spot. More...

Define output options

see: initializeOptionsViaDefine

#define DECIMAL_POSITIONS   4

#define EXTREME_SPOTS_DISOLVING   false

#define EXTREME_SPOTS_SHADING   false

#define PRINT_FILE_MEDIAN   true

Activates file output of median filtered image.

#define PRINT_FILE_SEGMENTED   true

Activates file output of segmented image.

#define PRINT_FILE_STATISTICS   true

hello Activates file output of spots statistics

#define SPOTS_MARKING   false

Define segmentation options

see: initializeOptionsViaDefine

#define FRAME_TYPE   FRAME_UNCHANGED

#define K_DEFAULT   0.5

#define MAX_AREA_DEFAULT   5000.0

#define MIN_AREA_DEFAULT   100.0

#define PERFORM_MEDIAN_FILTER   false

#define SEGMENTATION_METRIC   METRIC_TONE

Defines

#define KEEP_ORIGINAL_PATH   true

Do not modify this value.

#define OUTPUT_PATH   ""

When KEEP_ORIGINAL_PATH is set to false, this path is where the output is saved.

Typedefs

typedef enum _FileName FileName

Enumeration of the output files.

typedef _FilesOptions FilesOptions

Files information: paths, names and saving options.

typedef _OutputOptions OutputOptions

Holds all options on which where and how data should be output.

typedef enum _PixelMetric PixelMetric

Enumeration of the metrics that can be used to evaluate pixels distance.

typedef _PointDouble PointDouble

Position of a pixel in double format.

typedef _SegmentationOptions SegmentationOptions

Possible options of image segmentation.

typedef _SegmentationParameters SegmentationParameters

Parameters used in the segmentation algorithm.

typedef _SpotStatistics SpotStatistics

Characteristic properties of a spot.

Enumerations

enum _FileName {
  SOURCE_FILE, IMAGE_NAME, MEDIAN_FILE, SEGMENTED_FILE,
  SPOT_STATISTICS_FILE, FILES_NUMBER
}

Enumeration of the output files. More...

enum _PixelMetric { METRIC_EUCLIDEAN, METRIC_TONE, METRIC_HUE, METRICS_NUMBER }

Enumeration of the metrics that can be used to evaluate pixels distance. More...

Functions

void allocateFilesList (char **&filesList)

void copyImageBW (PixelPlane final, PixelPlane initial, int rows, int cols)

Copies the pixels in initial PixelPlane into final.

void copyImageColour (PixelPlane finalr, PixelPlane finalg, PixelPlane finalb, PixelPlane initialr, PixelPlane initialg, PixelPlane initialb, int rows, int cols)

void freeFilesList (char **fileslist)

Frees memory allocated by allocateFilesList.

void generateFileNames (char *filesList[], SegmentationParameters &parms)

Generates the names of the output files.

void getArgumentsFromUser (int argc, char *argv[], SegmentationParameters &parms, char *filesList[])

Stores the program arguments in their respective variables.

void initializeOptionsViaDefine (SegmentationOptions &segmentation, OutputOptions &output)

Initialize all options needed via data supplied through #DEFINES.

size_t segmentSimplePixelImage (SimplePixelImage const &inputImage, int *(**iSpotPixels), SegmentationOptions const &options, SpotStatistics *(*sSegmentationStatistics), FilesOptions const &files)

Segments a Simple Pixel Image according to the SegmentationOptions.

Detailed Description

hello Segmentation header.

The items included in this header are:

Segmentation function
- segmentSimplePixelImage
Initialization functions of segmentation parameters and options
Auxiliary functions (allocating functions)
- allocateFilesList
- freeFilesList

Define Documentation

#define DECIMAL_POSITIONS 4

Decimal positions of parameter K written on the file name of the segmented image.
See also:
generateFileNames

#define KEEP_ORIGINAL_PATH true

Do not modify this value.

Warning:
Until next version is released keep the value to true

#define PRINT_FILE_MEDIAN true

Activates file output of median filtered image.
Setting values:

false : no median filtered image file is written.
true : median filtered image is written in a file.

#define PRINT_FILE_SEGMENTED true

Activates file output of segmented image.
Setting values:

false : no segmented image file is written.
true : segmented image is written in a file.

Note:
The segmented image written on file is the one after spots disolving, marking and/or shading has been done. Whenever those options are activated.

#define PRINT_FILE_STATISTICS true

hello Activates file output of spots statistics
Setting values:

false : no spot statistics file is written.
true : a file with the statistics of each spot is written.

See also:
Spots statistics file format.

Typedef Documentation

typedef enum _FileName FileName

Enumeration of the output files.
The variables of this enumeration, are used to hold the position of the strings stored in _FilesOptions.
Example:

FilesOptions.list [MEDIAN_FILE] is a char pointer to the string holding the median file name.

typedef struct _FilesOptions FilesOptions

Files information: paths, names and saving options.

See also:
_FileName

typedef struct _OutputOptions OutputOptions

Holds all options on which where and how data should be output.
Which and where data should be output by file is the information held on the record files. The rest of records are intended to supply the most user's suitable appearance of the segmentation.
See also:
FilesOptions, _FilesOptions.

typedef enum _PixelMetric PixelMetric

Enumeration of the metrics that can be used to evaluate pixels distance.
Each of these metrics returns, for a pair of pixels,a real value in the range $ [0,1] $ . Value $ 0.0 $ is the nearest, and value $ 1.0 $ the furthest two pixels can be, speaking in terms of their colour properties.
See also:
mesureDistance, a function that can perfom any of the following pixel metrics.

typedef struct _SegmentationOptions SegmentationOptions

Possible options of image segmentation.
The segmentation options can be roughly gathered in 3 different groups:

Preprocesing options: they are applied before the segmentation algorithm is performed.
They are intended to improve the segmentation performance.

Algorithm parameters: they are used to perform the Felzenswalb-Huttenlocher algorithm.
The variation of these options can lead to very different segmentations of the same image, each with its own properties.

Postprocessing options: they are applied once the segmentation algorithm is performed.
They are intended to refine the segmentation supplied by the algorithm

Enumeration Type Documentation

enum _FileName

Enumeration of the output files.
The variables of this enumeration, are used to hold the position of the strings stored in _FilesOptions.
Example:

FilesOptions.list [MEDIAN_FILE] is a char pointer to the string holding the median file name.

Enumeration values:

SOURCE_FILE Position of the string holding the full filename of the input image. That is, the path is included in this string.

IMAGE_NAME Position of the string holding the input image filename. (without path)

MEDIAN_FILE Position of the string holding the name of the file where the median filtered image is saved.

SEGMENTED_FILE Position of the string holding the name of file where the segmented image is saved.

SPOT_STATISTICS_FILE Position of the string holding the name of the file where the statistics of every spot are listed.

FILES_NUMBER Counter of the strings contained in FilesOptions:

list string array
FilesOptions.shoulPrint bool array

enum _PixelMetric

Enumeration of the metrics that can be used to evaluate pixels distance.
Each of these metrics returns, for a pair of pixels,a real value in the range $ [0,1] $ . Value $ 0.0 $ is the nearest, and value $ 1.0 $ the furthest two pixels can be, speaking in terms of their colour properties.
See also:
mesureDistance, a function that can perfom any of the following pixel metrics.

Enumeration values:

METRIC_EUCLIDEAN Euclidean norm of the difference of two RGB pixels.
This metric takes the euclidean norm of the difference of two pixels $\| (r_1, g_1, b_1) - (r_2, g_2, b_2) \|$ as if they were 3-dimensional vectors $(r, g, b) \in \mathbb{R}^3$ where r, g and b take integer values on the interval $ [0,255] $
Note:
The standard euclidean norm is divided by $255\sqrt{3}$ this way the metric output is kept in the range $ [0,1] $

See also:
#mesureDistanceEuclidean so as to fully understand the calculation algorithm.

METRIC_TONE The angle between two RGB pixels.
Considering the $ u, v $ RGB pixels as vectors, $(r, g, b) \in \mathbb{R}^3$ , the angle between vectors is found by means of the dot product (i.e. $\widehat{u\,v} = \arccos ( \frac{u \cdot v}{\|u\| \|v\|}$ )
Note:
As the maximum possible angle between any pair of vectors in the $ (0,0,0) $ vertex of the RGB 255-cube is $\frac{\pi}{2}$ , the resultant angle is divided by $\frac{\pi}{2}$ in order to have the range $ [0,1] $ as the metric output.

Warning:
This is not a distance in the mathematical sense since different but proportional pixels have distance zero. Nevertheless it is indeed a distance in the set of RGB pixels under the equivalence relation of proportionality. That is, $u \sim v$ when $\exists \alpha \in \mathbb{R} \ | u = \alpha v$

See also:
#mesureDistanceTone so as to fully understand the calculation algorithm.

METRIC_HUE Difference of HUE between two pixels.
The hue is often given as a direction in the plane given in degrees, hue $\in [0,360)$ . So this mesure gives the angle comprised between the two hue directions (i.e. the difference of hue's)
Note:
As the maximum possible angle between any 2 vectors in the plane is $180^\circ$ , the resultant angle is divided by 180 in order to have the range $ [0,1] $ as the metric output.

Warning:
This is not a distance in the mathematical sense. The hue distance between different $ (r, g, b) $ pixels can be zero.

See also:
#mesureDistanceHue so as to fully understand the calculation algorithm.

METRICS_NUMBER Counter of the available pixel metrics.

Function Documentation

void allocateFilesList ( char **& filesList )

Allocates memory for files List and initializes them with the '\0' character

void copyImageColour ( PixelPlane finalr,

PixelPlane finalg,

PixelPlane finalb,

PixelPlane initialr,

PixelPlane initialg,

PixelPlane initialb,

int rows,

int cols

)

Copies each PixelPlane into the corresponding one. that is: copies initialr into finalr, initialg into finalg, and so on.

void generateFileNames ( char * filesList[],

SegmentationParameters & parms

)

Generates the names of the output files.
From the full file name (path+name) -stored in SOURCE_FILE position of filesList- this function generates the rest of files names and stores them in filesList.
These generated file names are the ones enumerated in _FileName.
filesList properties are detailed in _FilesOptions.list
Example:
Given filesList[SOURCE_FILE] , a pointer to the string "c:\anypath\anyname.ppm" this function generates the following strings of file names:

filesList[IMAGE_NAME] pointer to string "anyname.ppm"
filesList[MEDIAN_FILE] pointer to string "c:\anypath\anyname_med_n.ppm" where n is the size of the median window, it is set to 3 by default but modifiable via define #WINDOW_WIDTH
filesList[SEGMENTED_FILE] pointer to string "c:\anypath\anyname_segm_Kint_Kdec.ppm" . Kint stands for the integer part of K , and Kdec for its decimal part with as many digits as fixed by DECIMAL_POSITIONS. That is, if $ K = 2.327635 $ and DECIMAL_POSITIONS = 4 the output is "c:\anypath\anyname_segm_2_3276.ppm"
filesList[SPOT_STATISTICS_FILE] pointer to string "c:\anypath\anyname_stat_Kint_Kdec.ppm" . Where Kint and Kdec meaning is explained in the item above.

void getArgumentsFromUser ( int argc,

char * argv[],

SegmentationParameters & parms,

char * filesList[]

)

Stores the program arguments in their respective variables.
These arguments must be introduced in the following order:
Obligatory

File Name: saved in position SOURCE_FILE of the string array filesList

Optional

K
minarea
maxarea

void initializeOptionsViaDefine ( SegmentationOptions & segmentation,

OutputOptions & output

)

Initialize all options needed via data supplied through #DEFINES.

SegmentationOptions options are initialized with the values provided by Segmentation Default Options.
OutputOptions are initialized with the values provided by Output Default Options.

size_t segmentSimplePixelImage ( SimplePixelImage const & inputImage,

int *** iSpotPixels,

SegmentationOptions const & options,

SpotStatistics ** sSegmentationStatistics,

FilesOptions const & files

)

Segments a Simple Pixel Image according to the SegmentationOptions.

Parameters:

[in] inputImage The image to segment, stored in a _SimplePixelImage struct. It is advisable to begin with the function readPortableMapToSimplePixelImage to get easily started.

[out] iSpotPixels Array of the spots, where each spot is an array of the positions of its pixels. For instance: iSpotPixels[2][10] Gives the position of the 10th pixel of the 2nd spot.

[in] options By means of this _SegmentationOptions structure are passed all the option values. needed to carry out segmentation.

[in] files This _FilesOptions structure is used to pass

[out] sSegmentationStatistics It's an array of the type SpotStatistics. The position in the array represents the number of spot.

See also:
SimplePixelImage.h to know about all the image data types and functions

Generated on Wed Jul 14 17:25:04 2004 for Segmentation by

1.3.7


Classes
struct	_FilesOptions
	Files information: paths, names and saving options. More...
struct	_OutputOptions
	Holds all options on which where and how data should be output. More...
struct	_PointDouble
	Position of a pixel in `double` format. More...
struct	_SegmentationOptions
	Possible options of image segmentation. More...
struct	_SegmentationParameters
	Parameters used in the segmentation algorithm. More...
struct	_SpotStatistics
	Characteristic properties of a spot. More...
Define output options
see: initializeOptionsViaDefine
#define	DECIMAL_POSITIONS 4
#define	EXTREME_SPOTS_DISOLVING false
#define	EXTREME_SPOTS_SHADING false
#define	PRINT_FILE_MEDIAN true
	Activates file output of median filtered image.
#define	PRINT_FILE_SEGMENTED true
	Activates file output of segmented image.
#define	PRINT_FILE_STATISTICS true
	hello Activates file output of spots statistics
#define	SPOTS_MARKING false
Define segmentation options
see: initializeOptionsViaDefine
#define	FRAME_TYPE FRAME_UNCHANGED
#define	K_DEFAULT 0.5
#define	MAX_AREA_DEFAULT 5000.0
#define	MIN_AREA_DEFAULT 100.0
#define	PERFORM_MEDIAN_FILTER false
#define	SEGMENTATION_METRIC METRIC_TONE
Defines
#define	KEEP_ORIGINAL_PATH true
	Do not modify this value.
#define	OUTPUT_PATH ""
	When KEEP_ORIGINAL_PATH is set to `false`, this path is where the output is saved.
Typedefs
typedef enum _FileName	FileName
	Enumeration of the output files.
typedef _FilesOptions	FilesOptions
	Files information: paths, names and saving options.
typedef _OutputOptions	OutputOptions
	Holds all options on which where and how data should be output.
typedef enum _PixelMetric	PixelMetric
	Enumeration of the metrics that can be used to evaluate pixels distance.
typedef _PointDouble	PointDouble
	Position of a pixel in `double` format.
typedef _SegmentationOptions	SegmentationOptions
	Possible options of image segmentation.
typedef _SegmentationParameters	SegmentationParameters
	Parameters used in the segmentation algorithm.
typedef _SpotStatistics	SpotStatistics
	Characteristic properties of a spot.
Enumerations
enum	_FileName { SOURCE_FILE, IMAGE_NAME, MEDIAN_FILE, SEGMENTED_FILE, SPOT_STATISTICS_FILE, FILES_NUMBER }
	Enumeration of the output files. More...
enum	_PixelMetric { METRIC_EUCLIDEAN, METRIC_TONE, METRIC_HUE, METRICS_NUMBER }
	Enumeration of the metrics that can be used to evaluate pixels distance. More...
Functions
void	allocateFilesList (char **&filesList)
void	copyImageBW (PixelPlane final, PixelPlane initial, int rows, int cols)
	Copies the pixels in initial `PixelPlane` into final.
void	copyImageColour (PixelPlane finalr, PixelPlane finalg, PixelPlane finalb, PixelPlane initialr, PixelPlane initialg, PixelPlane initialb, int rows, int cols)
void	freeFilesList (char **fileslist)
	Frees memory allocated by allocateFilesList.
void	generateFileNames (char *filesList[], SegmentationParameters &parms)
	Generates the names of the output files.
void	getArgumentsFromUser (int argc, char argv[], SegmentationParameters &parms, char filesList[])
	Stores the program arguments in their respective variables.
void	initializeOptionsViaDefine (SegmentationOptions &segmentation, OutputOptions &output)
	Initialize all options needed via data supplied through #DEFINES.
size_t	segmentSimplePixelImage (SimplePixelImage const &inputImage, int (iSpotPixels), SegmentationOptions const &options, SpotStatistics (*sSegmentationStatistics), FilesOptions const &files)
	Segments a Simple Pixel Image according to the SegmentationOptions.