only-pie/include/sane/sanei_ir.h File Reference

#include <stdint.h>

Go to the source code of this file.

Data Structures
union	SANEI_IR_bufptr
	Pointer to access values of different bit depths. More...
Defines
#define	SAMPLE_SIZE   40000
#define	HISTOGRAM_SHIFT   8
#define	HISTOGRAM_SIZE   (1 << HISTOGRAM_SHIFT)
#define	SAFE_LOG(x)   ( ((x) > 0.0) ? log ((x)) : (0.0) )
#define	MAD_WIN2_SIZE(x)   ( (((x) * 4) / 3) | 1 )
Functions
void	sanei_ir_init (void)
SANE_Status	sanei_ir_create_norm_histogram (const SANE_Parameters *params, const SANEI_IR_bufptr img_data, double **histogram)
	Create the normalized histogram of a grayscale image.
SANE_Status	sanei_ir_threshold_yen (const SANE_Parameters *params, double *norm_histo, int *thresh)
	Implements Yen's thresholding method.
SANE_Status	sanei_ir_threshold_otsu (const SANE_Parameters *params, double *norm_histo, int *thresh)
	Implements Otsu's thresholding method.
SANE_Status	sanei_ir_threshold_maxentropy (const SANE_Parameters *params, double *norm_histo, int *thresh)
	Implements a Maximum Entropy thresholding method.
SANE_Status	sane_ir_RGB_luminance (SANE_Parameters *params, const SANEI_IR_bufptr *in_img, SANEI_IR_bufptr *out_img, SANE_Bool scale8)
	Generate gray scale luminance image from separate R, G, B images.
SANE_Status	sane_ir_to_8bit (SANE_Parameters *params, const SANEI_IR_bufptr in_img, SANE_Parameters *out_params, SANEI_IR_bufptr *out_img)
	Convert image from >8 bit depth to an 8 bit image.
SANE_Status	sane_ir_ln_table (int len, double **lut_ln)
	Allocate and initialize logarithmic lookup table.
SANE_Status	sane_ir_spectral_clean (const SANE_Parameters *params, double *lut_ln, const SANEI_IR_bufptr red_data, SANEI_IR_bufptr ir_data)
	Reduces red spectral overlap from an infrared image plane.
SANE_Status	sanei_ir_filter_mean (const SANE_Parameters *params, const SANEI_IR_bufptr in_img, SANEI_IR_bufptr out_img, int win_rows, int win_cols)
	Optimized mean filter.
SANE_Status	sanei_ir_filter_madmean (const SANE_Parameters *params, const SANEI_IR_bufptr in_img, SANE_Byte **out_img, int win_size, int a_val, int b_val)
	Find noise by adaptive thresholding.
void	sanei_ir_add_threshold (const SANE_Parameters *params, const SANEI_IR_bufptr in_img, SANE_Byte *mask_img, int threshold)
	Add dark pixels to mask from static threshold.
void	sane_ir_manhattan_dist (const SANE_Parameters *params, const SANE_Byte *mask_img, unsigned int *dist_map, unsigned int *idx_map, unsigned int erode)
	Calculates minimal Manhattan distances for an image mask.
void	sane_ir_dilate (const SANE_Parameters *params, SANE_Byte *mask_img, unsigned int *dist_map, unsigned int *idx_map, int by)
	Dilate or erode a mask image.
void	sanei_ir_find_crop (const SANE_Parameters *params, unsigned int *dist_map, int inner, int *edges)
	Suggest cropping for dark margins of positive film.
SANE_Status	sanei_ir_dilate_mean (const SANE_Parameters *params, SANEI_IR_bufptr *in_img, SANE_Byte *mask_img, int dist_max, int expand, int win_size, SANE_Bool smooth, int inner, int *crop)
	Dilate clean image parts into dirty ones and smooth int inner,.

---

Detailed Description

This file provides an interface to the sanei_ir functions for utilizing the infrared plane

Copyright (C) 2012 Michael Rickmann <mrickma@gwdg.de>

This file is part of the SANE package.

Essentially three things have to be done:

• 1) reduce red spectral overlap from the infrared (ired) plane
• 2) find the dirt
• 3) replace the dirt

• 1) is mainly adressed by sane_ir_spectral_clean
• 2) by sanei_ir_filter_madmean
• 3) by sanei_ir_dilate_mean

Definition in file sanei_ir.h.

---

Define Documentation

#define HISTOGRAM_SHIFT   8

standard histogram size

Definition at line 28 of file sanei_ir.h.

#define HISTOGRAM_SIZE   (1 << HISTOGRAM_SHIFT)

Definition at line 29 of file sanei_ir.h.

#define MAD_WIN2_SIZE

(

x

)

( (((x) * 4) / 3) | 1 )

MAD filter: 2nd window size

Definition at line 33 of file sanei_ir.h.

#define SAFE_LOG

(

x

)

( ((x) > 0.0) ? log ((x)) : (0.0) )

define log (0) = 0

Definition at line 31 of file sanei_ir.h.

#define SAMPLE_SIZE   40000

maximal for random sampling

Definition at line 26 of file sanei_ir.h.

---

Function Documentation

void sane_ir_dilate	(	const SANE_Parameters *	params,
		SANE_Byte *	mask_img,
		unsigned int *	dist_map,
		unsigned int *	idx_map,
		int	by
	)

Dilate or erode a mask image.

Parameters:

[in]	params	pointer to image description
	mask_img	pointer to binary image (0, 255)
	dist_map	integer pointer to map of closest distances
	idx_map	integer pointer to indices of closest pixels
[in]	by	number of pixels, > 0 dilate, < 0 erode

Note:

by > 0 will enlarge the 0 valued area

Definition at line 1169 of file sanei_ir.c.

SANE_Status sane_ir_ln_table	(	int	len,
		double **	lut_ln
	)

Allocate and initialize logarithmic lookup table.

Parameters:

[in]	length	of table, usually 1 << depth
[out]	lut_ln	adress of pointer to allocated table

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

Note:

natural logarithms are provided

Definition at line 550 of file sanei_ir.c.

void sane_ir_manhattan_dist	(	const SANE_Parameters *	params,
		const SANE_Byte *	mask_img,
		unsigned int *	dist_map,
		unsigned int *	idx_map,
		unsigned int	erode
	)

Calculates minimal Manhattan distances for an image mask.

Parameters:

[in]	params	pointer to image description
[in]	mask_img	pointer to binary image (0, 255)
[out]	dist_map	integer pointer to map of closest distances
[out]	idx_map	integer pointer to indices of closest pixels
[in]	erode	== 0: closest pixel has value 0, != 0: is 255

manhattan_dist takes a mask image consisting of 0 or 255 values. Given that a 0 represents a dirty pixel and erode != 0, manhattan_dist will calculate the shortest distance to a clean (255) pixel and record which pixel that was so that the clean parts of the image can be dilated into the dirty ones. Thresholding can be done on the distance. Conversely, if erode == 0 the distance of a clean pixel to the closest dirty one is calculated which can be used to dilate the mask.

extended and C version of http://ostermiller.org/dilate_and_erode.html

Definition at line 1063 of file sanei_ir.c.

SANE_Status sane_ir_RGB_luminance	(	SANE_Parameters *	params,
		const SANEI_IR_bufptr *	in_img,
		SANEI_IR_bufptr *	out_img,
		SANE_Bool	scale8
	)

Generate gray scale luminance image from separate R, G, B images.

Parameters:

	params	points to image description
[in]	in_img	pointer to at least 3 planes of image data
[out]	out_img	newly allocated image
[in]	scale8	if true output image will be 8 bit deep

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory
• SANE_STATUS_UNSUPPORTED - wrong input bit depth

Note:

out_img has to be freed by the calling routine.

on input params describe a single color plane, on output params are updated if image depth is scaled

Definition at line 432 of file sanei_ir.c.

SANE_Status sane_ir_spectral_clean	(	const SANE_Parameters *	params,
		double *	lut_ln,
		const SANEI_IR_bufptr	red_data,
		SANEI_IR_bufptr	ir_data
	)

Reduces red spectral overlap from an infrared image plane.

Parameters:

[in]	params	pointer to image description
[in]	lut_ln	pointer lookup table if NULL it is dynamically handled
[in]	red_data	pointer to red image plane
	ired_data	pointer to ired image plane

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

This routine is based on the observation that the relation beween the infrared value ired and the red value red of an image point can be described by ired = b + a * ln (red). First points are randomly sampled to calculate the linear regression coefficent a. Then ired' = ired - a * ln (red) is calculated for each pixel. Finally, the ir' image is scaled between 0 and maximal value. For the logarithms a lookup table is used. Negative films show very little spectral overlap but positive film usually has to be cleaned. As we do a statistical measure of the film here dark margins and lumps of dirt have to be excluded.

Note:

original ired data are replaced by the cleaned ones

Definition at line 576 of file sanei_ir.c.

SANE_Status sane_ir_to_8bit	(	SANE_Parameters *	params,
		const SANEI_IR_bufptr	in_img,
		SANE_Parameters *	out_params,
		SANEI_IR_bufptr *	out_img
	)

Convert image from >8 bit depth to an 8 bit image.

Parameters:

[in]	params	pimage description
[in]	in_img	points to input image data
[out]	out_params	if != NULL receives description of new image
[out]	out_img	newly allocated 8-bit image

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory
• SANE_STATUS_UNSUPPORTED - wrong input bit depth

Note:

out_img has to be freed by the calling routine,

Definition at line 494 of file sanei_ir.c.

void sanei_ir_add_threshold	(	const SANE_Parameters *	params,
		const SANEI_IR_bufptr	in_img,
		SANE_Byte *	mask_img,
		int	threshold
	)

Add dark pixels to mask from static threshold.

Parameters:

[in]	params	pointer to image description
[in]	in_img	pointer to grey scale image
	mask_img	pointer to binary image (0, 255)
[in]	threshold	below which the pixel is set 0

Definition at line 1029 of file sanei_ir.c.

SANE_Status sanei_ir_create_norm_histogram	(	const SANE_Parameters *	params,
		const SANEI_IR_bufptr	img_data,
		double **	histogram
	)

Create the normalized histogram of a grayscale image.

Parameters:

[in]	params	describes image
[in]	img_data	image pointer { grayscale }
[out]	histogram	an array of double with histogram

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

Note:

histogram has to be freed by calling routine

Definition at line 132 of file sanei_ir.c.

SANE_Status sanei_ir_dilate_mean	(	const SANE_Parameters *	params,
		SANEI_IR_bufptr *	in_img,
		SANE_Byte *	mask_img,
		int	dist_max,
		int	expand,
		int	win_size,
		SANE_Bool	smooth,
		int	inner,
		int *	crop
	)

Dilate clean image parts into dirty ones and smooth int inner,.

Parameters:

[in]	params	pointer to image description
	in_img	array of pointers to color planes of image
[in]	mask_img	pointer to dirt mask image
[in]	dist_max	threshold up to which dilation is done
[in]	expand	the dirt mask before replacing the pixels
[in]	win_size	size of adaptive mean filtering window
[in]	smooth	triangular filter whole image for grain removal
[in]	inner	find crop within or outside the image's edges
[out]	crop	array of 4 integers, if non-NULL, top, bottom, left and right values for cropping are returned.

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

The main purpose of this routine is to replace dirty pixels. As spin-off it obtains half of what is needed for film grain smoothening and most of how to crop positive film. To speed things up these functions are also implemented.

Definition at line 1296 of file sanei_ir.c.

SANE_Status sanei_ir_filter_madmean	(	const SANE_Parameters *	params,
		const SANEI_IR_bufptr	in_img,
		SANE_Byte **	out_img,
		int	win_size,
		int	a_val,
		int	b_val
	)

Find noise by adaptive thresholding.

Parameters:

[in]	params	pointer to image description
[in]	in_img	pointer to grey scale image
[out]	out_img	address of pointer to newly allocated binary image
[in]	win_size	Size of filtering window
[in]	a_val	Parameter, below is definetly clean
[in]	b_val	Parameter, above is definetly noisy

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

This routine follows the concept of Crnojevic's MAD (median of the absolute deviations from the median) filter. The first median filter step is replaced with a mean filter. The dirty pixels which we wish to remove are always darker than the real signal. But at high resolutions the scanner may generate some noise and the ired cleaning step can reverse things. So a maximum filter will not do. The second median is replaced by a mean filter to reduce computation time. Inspite of these changes Crnojevic's recommendations for the choice of the parameters "a" and "b" are still valid when scaled to the color depth.

Crnojevic recommends 10 < a_val < 30 and 50 < b_val < 100 for 8 bit color depth

Note:

a_val, b_val are scaled by the routine according to bit depth

"0" in the mask output is regarded "dirty", 255 "clean"

1. Crnojevic V. (2005) "Impulse Noise Filter with Adaptive Mad-Based Threshold" Proc. of the IEEE Int. Conf. on Image Processing, 3: 337-340

Definition at line 915 of file sanei_ir.c.

SANE_Status sanei_ir_filter_mean	(	const SANE_Parameters *	params,
		const SANEI_IR_bufptr	in_img,
		SANEI_IR_bufptr	out_img,
		int	win_rows,
		int	win_cols
	)

Optimized mean filter.

Parameters:

[in]	params	pointer to image description
[in]	in_img	Pointer to grey scale image data
[out]	out_img	Pointer to grey scale image data
[in]	win_rows	Height of filtering window, odd
[in]	win_cols	Width of filtering window, odd

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory
• SANE_STATUS_INVAL - wrong window size

Note:

At the image margins the size of the filtering window is adapted. So there is no need to pad the image.

Memory for the output image has to be allocated before

Definition at line 731 of file sanei_ir.c.

void sanei_ir_find_crop	(	const SANE_Parameters *	params,
		unsigned int *	dist_map,
		int	inner,
		int *	edges
	)

Suggest cropping for dark margins of positive film.

Parameters:

[in]	params	pointer to image description
[in]	dist_map	integer pointer to map of closest distances
[in]	inner	crop within (!=0) or outside (==0) the image's edges
[out]	edges	pointer to array holding top, bottom, left and right edges

The distance map as calculated by sane_ir_manhattan_dist contains distances to the next clean pixel. Dark margins are detected as dirt. So the first/last rows/columns tell us how to crop. This is rather fast if the distance map has been calculated anyhow.

Definition at line 1213 of file sanei_ir.c.

void sanei_ir_init

(

void

)

Initialize sanei_ir.

Call this before any other sanei_ir function.

Definition at line 52 of file sanei_ir.c.

SANE_Status sanei_ir_threshold_maxentropy	(	const SANE_Parameters *	params,
		double *	norm_histo,
		int *	thresh
	)

Implements a Maximum Entropy thresholding method.

Parameters:

[in]	params	describes image
[in]	norm_histo	points to a normalized histogram
[out]	thresh	found threshold

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

1. Kapur J.N., Sahoo P.K., and Wong A.K.C. (1985) "A New Method for Gray-Level Picture Thresholding Using the Entropy of the Histogram" Graphical Models and Image Processing, 29(3): 273-285
2. M. Emre Celebi, 06.15.2007, fourier_0.8 http://sourceforge.net/projects/fourier-ipal/
3. ImageJ Multithresholder plugin, http://rsbweb.nih.gov/ij/plugins/download/AutoThresholder.java

Definition at line 332 of file sanei_ir.c.

SANE_Status sanei_ir_threshold_otsu	(	const SANE_Parameters *	params,
		double *	norm_histo,
		int *	thresh
	)

Implements Otsu's thresholding method.

Parameters:

[in]	params	describes image
[in]	norm_histo	points to a normalized histogram
[out]	thresh	found threshold

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

1. Otsu N. (1979) "A Threshold Selection Method from Gray Level Histograms" IEEE Trans. on Systems, Man and Cybernetics, 9(1): 62-66
2. M. Emre Celebi, 06.15.2007, fourier_0.8 http://sourceforge.net/projects/fourier-ipal/

Definition at line 249 of file sanei_ir.c.

SANE_Status sanei_ir_threshold_yen	(	const SANE_Parameters *	params,
		double *	norm_histo,
		int *	thresh
	)

Implements Yen's thresholding method.

Parameters:

[in]	params	describes image
[in]	norm_histo	points to a normalized histogram
[out]	thresh	found threshold

Returns:

• SANE_STATUS_GOOD - success
• SANE_STATUS_NO_MEM - if out of memory

1. Yen J.C., Chang F.J., and Chang S. (1995) "A New Criterion for Automatic Multilevel Thresholding" IEEE Trans. on Image Processing, 4(3): 370-378
2. Sezgin M. and Sankur B. (2004) "Survey over Image Thresholding Techniques and Quantitative Performance Evaluation" Journal of Electronic Imaging, 13(1): 146-165
3. M. Emre Celebi, 06.15.2007, fourier_0.8, http://sourceforge.net/projects/fourier-ipal/
4. ImageJ Multithresholder plugin, http://rsbweb.nih.gov/ij/plugins/download/AutoThresholder.java

Definition at line 173 of file sanei_ir.c.