VC nano3D-Z

Collaboration diagram for VC nano3D-Z:

Data Structures
struct	VCNano3dZResult
	Nano3D-Z Measurement Result. More...
struct	_VCNano3dZInit
	Nano3D-Z Parameters only configurable during Initialization. More...
struct	VCNano3dZVolatile
	Volatile Values of Nano3D-Z Description Struct. More...
struct	VCNano3dZExternal
	Externally delivered Values of Nano3D-Z Struct. More...
struct	VCNano3dZDesc
	Nano3D-Z Description. More...
struct	VCNano3dZCfg
	Nano3D-Z Settings. More...
struct	_VCNano3dZ
	Nano3D-Z Custom Struct. More...
enum	VCNano3dZSelect { NANO3DZSEL_UNSET = 0xFF, NANO3DZSEL_OPT = 0, NANO3DZSEL_NR = 1, NANO3DZSEL_PEAK = 2 }
	Laser Line Slice Selection Method. More...
enum	VCErrNano3dZ {   ERR_NANO3DZ_NONE = ERR_NONE, ERR_NANO3DZ_DESPECLE_KX = -901, ERR_NANO3DZ_DESPECLE_KY = -902, ERR_NANO3DZ_BG_SUB_KY = -903,   ERR_NANO3DZ_LASER_THR = -904, ERR_NANO3DZ_LASER_DYMIN = -905, ERR_NANO3DZ_LASER_DYMAX = -906, ERR_NANO3DZ_LASER_SEL = -907,   ERR_NANO3DZ_LASER_SEL_NR = -908, ERR_NANO3DZ_LASER_DYOPT = -909 }
	Error Codes for VCNano3dZ struct. More...
I32	vc_nano3dz_external_mapper_toMM (VCCaptCfg *cpt)
	Calculates Nano3D-Z Result Pixel Data to World MM Data conveniently. More...
I32	vc_nano3dz_external_mapper_toMM_ (F32 *xPX, F32 *yPX, F32 *xMM, F32 *yMM, I32 cnt, struct _VCNano3dZMappers *mappers)
	Calculates Nano3D-Z Result Pixel Data to World MM Data. More...
I32	vc_nano3dz_external_mapper_toPX_ (F32 *xMM, F32 *yMM, F32 *xPX, F32 *yPX, I32 cnt, struct _VCNano3dZMappers *mappers)
	Calculates Nano3D-Z World MM Data to Pixel Data. More...
#define	VCNano3dZInit_Default   { CUSTOMID_NANO3DZ, 0, {'\0'} }
	Nano3D-Z Initialization Default Settings. More...
#define	str_VCErrNano3dZ(e)
	Error Code String for VCNano3dZ struct. More...
#define	vc_nano3dz_laser_switch(onIff1, pCamCfg)   vc_nano3dz_laser_switch_(onIff1, &((pCamCfg)->d.gpio))
	Convenience Laser On/Off Switch Function (Macro). More...
#define	vc_nano3dz_external_mapper_toMM_F32F32( xPX, yPX, xMM, yMM, cnt, pSenCfg)   vc_nano3dz_external_mapper_toMM_( xPX, yPX, xMM, yMM, cnt,(pSenCfg)->c.nano3dz->cfg.d.e.mappers)
	Calculates Nano3D-Z Result Pixel Data to World MM Data (Macro). More...
#define	vc_nano3dz_external_mapper_toPX( xMM, yMM, xPX, yPX, cnt, pSenCfg)   vc_nano3dz_external_mapper_toPX_( xMM, yMM, xPX, yPX, cnt,(pSenCfg)->c.nano3dz->cfg.d.e.mappers)
	Calculates Nano3D-Z World MM Data to Pixel Data (Macro). More...
#define	VCSenCustomCalls_Nano3dZ
	Nano3D-Z Customizer Data for the Sensor Initialization. More...

Detailed Description

Everything listed here is designed for the VC nano3D-Z hardware.

Note

Due to laser security there are certain limitations for the shutter time and the laser enable control: Laser safety overrules all other settings. Refer to the hardware manual of the camera if the laser is permanently off (laser warden) or brightness changes are encountered (duty cycle limitation).

The laser must be turned on before by, for example, using the convenience macro vc_nano3dz_laser_switch().

The acquired image will be processed by the FPGA the following way:

Estimating relevant laser pixels.

The selected laser pixels are scanned for each column to get the slice result:

@ref VCNano3dZSlice values.

Note

The flip setting at the VCSenCfg struct has a different meaning to this type of camera: SENFLIP_VERT will not flip the image vertically. Instead, the application of SENFLIP_VERT to sen->flip starts the laser line search from bottom instead of from top, for example if NANO3DZSEL_NR is chosen at laserSelect it searches for the n-th line from bottom.

Inappropriate image content like glares may generate misleading data if bgSubKy at the VCNano3dZCfg is set to a value higher than 0.

Pseudo-shape by bgSubKy due to malicious glare.

---

Data Structure Documentation

VCNano3dZResult

struct VCNano3dZResult

This structure keeps the result of the measurement done at laser slices. Although there may pass multiple lines through a slice, only the measurement of one line segment is provided. Which one to be selected is controlled by settings at the VCNano3dZCfg.

Figure showing @ref VCNano3dZSlice values.

The mapped coordinates, mmX and mmZ are available after successful application of the external function vc_nano3dz_external_mapper_toMM(). On success the variable mmIff1 is set to 1 at struct VCNano3dZResult.

The output positions x, y, … are independent of the ROI settings, like sensors x0, y0, dx, dy, flip: They are the true sensor pixel coordinates.

Result data for a slice is undefined if no laser line is detected at it, hence it should always be checked if dy is not zero.

Note

Due to the reduced information, activated subsampling or binning will lead to less precise measurement results.

 ...
 I32              i;
 VCNano3dZ       *nano3dz = cpt[tgt].sen[sn].c.nano3dz;   // abbreviation
 VCNano3dZResult *result  = &(nano3dz->result);           // abbreviation
 ...
 vc_capt(&(cpt[tgt]);
 ...
 
for(i= 0; i< result->sliceCnt; i++)
  if(result->dy[i]>0)
      printf("Slice %4d:  (x,y):(%4.0f,%7.2f) (mmX,mmZ):(%+8.3f,%+8.3f)<-Garbage\n", i,
             result->x[i], result->y[i], result->mmX[i], result->mmZ[i]);
 
rc =  vc_nano3dz_external_mapper_toMM(&(cpt[tgtIdx]));
if(rc<0){ee=-11+100*rc; goto end;}
 
for(i= 0; i< result->sliceCnt; i++)
  if(result->dy[i]>0)
      printf("Slice %4d:  (x,y):(%4.0f,%7.2f) (mmX,mmZ):(%+8.3f,%+8.3f)<-OK\n", i,
             result->x[i], result->y[i], result->mmX[i], result->mmZ[i]);

The example code above shows how to access the result data easily, and that the pixel-to-mm conversion result is only available after calling the function vc_nano3dz_external_mapper_toMM(); unavailable data is identified by checking the value of the parameter dy.

Data Fields
U32	sliceCnt	Number of available Laser Line Slices.
I8	mmIff1	Slice mm coordinates mmX and mmZ are available if 1, set by the external function vc_nano3dz_external_mapper_toMM().
F32 *	mmX	Available if mmIff1 is 1: Laser Line Pixel coordinate x as World coodinate. sliceCnt Indices.
F32 *	mmZ	Available if mmIff1 is 1: Laser Line Pixel coordinate y as World coodinate. sliceCnt Indices.
F32 *	x	x Position of this Laser Line Slice. sliceCnt Indices.
F32 *	y	Subpixel precise Centroid y Position of the Laser Line, unreliable if sat is 1. sliceCnt Indices.
I16 *	y0	Minimum y Position at the Laser Line. sliceCnt Indices.
I16 *	dy	y-Size of the Laser Line, 0 if no Laser Line is Detected. sliceCnt Indices.
I8 *	sat	Saturation before application of vertical high pass filter if 1, y position is unreliable if 1 (Reducing shutter time may help). sliceCnt Indices.
I16 *	vMax	Maximum peak amplitude of the Laser Line. sliceCnt Indices.
I32 *	sv	Sum of all grey values of Laser Line (moment M0). sliceCnt Indices.
I32 *	svy	Sum of all grey values Weighted by their y Position of Laser Line (moment M1). sliceCnt Indices.
I8 *	nr	Laser Line Number from Top (negative: from Bottom) of this Slice, starting with ± 1, for numbers exceeding ± 7 the value is ± 7. sliceCnt Indices.
U32	maxSliceCnt	Maximum possible number of Laser Line Slices.

_VCNano3dZInit

struct _VCNano3dZInit

This structure keeps nano3D-Z parameters which are only configurable during Initialization.

Usage example:

...
VCSenInit        senInit     = VCSenInit_Default;
VCNano3dZInit    nano3dzInit = VCNano3dZInit_Default;
...
nano3dzInit.disableImgIff1 = 1;
...
senInit.cInit.nano3dz  = &nano3dzInit;
...
rc =  vc_cam_init(..., &senInit);
...

Data Fields
VCCustomId	customId	must be CUSTOMID_NANO3DZ, do not change: Struct Type Identifier
I32	disableImgIff1	To fasten processing, set this to 1: No image is available then, only data at VCNano3dZResult.
char	pathMapper[36]	Reserved to define individual mappings.

VCNano3dZVolatile

struct VCNano3dZVolatile

This structure keeps volatile data changing for each recording.

Data Fields
U64 *	pcog	Raw Data for VCNano3dZResult calculation
U64 *	pcogInfo	Raw Data for VCNano3dZResult calculation

VCNano3dZExternal

struct VCNano3dZExternal

This structure keeps externally delivered data.

Data Fields
struct _VCNano3dZMappers *	mappers	Mapper data for PX<->MM conversion.

VCNano3dZDesc

struct VCNano3dZDesc

This structure keeps descripting information. Never change anything in here, also not in substructures!

Collaboration diagram for VCNano3dZDesc:

Data Fields
VCNano3dZVolatile	v	Raw data for VCNano3dZResult calculation
VCNano3dZExternal	e	Description of Settings filled externally.
U32	cogMaxCnt	Information on volatile raw data.

VCNano3dZCfg

struct VCNano3dZCfg

This structure keeps settings specifically for the Nano3D-Z. We will initialize it, but not change anything in it except for the VCNano3dZDesc struct.

Warning

Do not change parameters between calling vc_capt_request() and vc_capt_wait(), or result values, for example the values in y of the VCNano3dZResult will be wrong; the state of the corresponding VCSenVolatile struct is not SENSTATE_IDLE during that period.

Collaboration diagram for VCNano3dZCfg:

Data Fields
I32	despecleKx	Preprocess image by using a horizontal averaging over [1,3,5,7] pixels.
I32	despecleKy	Preprocess image by using a vertical averaging over [1,3,5,7] pixels.
I32	bgSubKy	0: no vertical high pass filter, [2..31]: Vertical high pass filter ([1]: black image).
I32	laserThr	Pixels with grey value greater than that value are interpreted as laser illuminated [0..255].
I32	laserDyMin	[0..63], laserDyMin + 1 = Minimum vertical thickness in pixel to be accepted as laser line segment.
I32	laserDyMax	Maximum vertical thickness [0..63] in pixel to be accepted as laser line segment.
VCNano3dZSelect	laserSelect	Laser Line Selection Mode, activates use of different configuration parameters depending on its value.
I32	laserSelectNr	Used with approriate VCNano3dZSelect: Laser line number [1..7] from top; for from bottom: Set sen->flip to SENFLIP_VERT additionally.
I32	laserDyOpt	Used with approriate VCNano3dZSelect: Vertical thickness closest to this value [0..63] in pixel is chosen.
VCNano3dZDesc	d	Descriptive, never change anything in here!

_VCNano3dZ

struct _VCNano3dZ

A pointer to this structure is available over the Sensor struct's custom union VCSenCustom at sen[]. c->nano3dz.

Collaboration diagram for _VCNano3dZ:

Data Fields
VCCustomId	customId	must be CUSTOMID_NANO3DZ, do not change: Struct Type Identifier
VCNano3dZCfg	cfg	Configuration for the result
VCNano3dZResult	result	Measurement result

Macro Definition Documentation

VCNano3dZInit_Default

#define VCNano3dZInit_Default   { CUSTOMID_NANO3DZ, 0, {'\0'} }

The Nano3D-Z Configuration used if NULL is given as Initialisation Parameter.

str_VCErrNano3dZ

#define str_VCErrNano3dZ

(

e

)

Value:

            (ERR_NANO3DZ_NONE         == (e))?("NONE                ") \
           :(ERR_NANO3DZ_DESPECLE_KX  == (e))?("NANO3DZ_DESPECLE_KX ") \
           :(ERR_NANO3DZ_DESPECLE_KY  == (e))?("NANO3DZ_DESPECLE_KY ") \
           :(ERR_NANO3DZ_BG_SUB_KY    == (e))?("NANO3DZ_BG_SUB_KY   ") \
           :(ERR_NANO3DZ_LASER_THR    == (e))?("NANO3DZ_LASER_THR   ") \
           :(ERR_NANO3DZ_LASER_DYMIN  == (e))?("NANO3DZ_LASER_DYMIN ") \
           :(ERR_NANO3DZ_LASER_DYMAX  == (e))?("NANO3DZ_LASER_DYMAX ") \
           :(ERR_NANO3DZ_LASER_SEL    == (e))?("NANO3DZ_LASER_SEL   ") \
           :(ERR_NANO3DZ_LASER_SEL_NR == (e))?("NANO3DZ_LASER_SEL_NR") \
           :(ERR_NANO3DZ_LASER_DYOPT  == (e))?("NANO3DZ_LASER_DYOPT ") \
           :("UNKNOWN")

This macro returns a String for the enum VCErrNano3dZ.

vc_nano3dz_laser_switch

#define vc_nano3dz_laser_switch	(		onIff1,
			pCamCfg
	)		vc_nano3dz_laser_switch_(onIff1, &((pCamCfg)->d.gpio))

This macro can switch the laser on/off, i.e. sets the gpio Nr. 4 to 1 or 0 based on selection followed by a delay for laser power up.

Note

However this macro does not turn on/off the trigger warden or laser warden, which can prevent the laser from glowing! Refer to the hardware manual.

vc_nano3dz_laser_switch() is a macro which calls vc_nano3dz_laser_switch_() where more information may be found.

vc_nano3dz_external_mapper_toMM_F32F32

#define vc_nano3dz_external_mapper_toMM_F32F32	(		xPX,
			yPX,
			xMM,
			yMM,
			cnt,
			pSenCfg
	)		vc_nano3dz_external_mapper_toMM_( xPX, yPX, xMM, yMM, cnt,(pSenCfg)->c.nano3dz->cfg.d.e.mappers)

This macro calculates Nano3D-Z result pixel data of the laser line to world MM data by transforming the array-like lists xPx and yPx to their output values at xMM and yMM.

vc_nano3dz_external_mapper_toMM_F32F32() is a macro which calls vc_nano3dz_external_mapper_toMM_() where more information can be found.

vc_nano3dz_external_mapper_toPX

#define vc_nano3dz_external_mapper_toPX	(		xMM,
			yMM,
			xPX,
			yPX,
			cnt,
			pSenCfg
	)		vc_nano3dz_external_mapper_toPX_( xMM, yMM, xPX, yPX, cnt,(pSenCfg)->c.nano3dz->cfg.d.e.mappers)

This macro calculates Nano3D-Z result world MM data of the laser line to pixel data by transforming the array-like lists xMM and yMM to their output values at xPx and yPx.

vc_nano3dz_external_mapper_toPX() is a macro which calls vc_nano3dz_external_mapper_toPX_() where more information can be found.

VCSenCustomCalls_Nano3dZ

#define VCSenCustomCalls_Nano3dZ

Value:

        {                                  \
            CUSTOMID_NANO3DZ,              \
            &vc_nano3dz_cInit_alloc  ,     \
            &vc_nano3dz_cInit_free   ,     \
            &vc_nano3dz_cInit_copy   ,     \
            &vc_nano3dz_cInit_default,     \
            &vc_nano3dz_alloc        ,     \
            &vc_nano3dz_free         ,     \
            &vc_nano3dz_copy         ,     \
            &vc_nano3dz_default      ,     \
            &vc_nano3dz_init         ,     \
            &vc_nano3dz_deinit       ,     \
            &vc_nano3dz_prepare      ,     \
            &vc_nano3dz_finalize     ,     \
            &vc_nano3dz_verify       ,     \
        }

The Nano3D-Z Customizer Data for the Sensor Initialization.

Enumeration Type Documentation

VCNano3dZSelect

enum VCNano3dZSelect

This enum identifies the selection method for the laser line slices.

Enumerator
NANO3DZSEL_UNSET	Unset/Unused
NANO3DZSEL_OPT	Select laser line with vertical thickness closest to laserDyOpt pixels.
NANO3DZSEL_NR	Select the laserSelectNr th laser line from top.
NANO3DZSEL_PEAK	Select the laser line containing the maximum grey value.

VCErrNano3dZ

enum VCErrNano3dZ

This enum contains error codes for a Nano 3D Z struct verification.

Enumerator
ERR_NANO3DZ_NONE	No Error detected.
ERR_NANO3DZ_DESPECLE_KX	Value of despecleKx is invalid.
ERR_NANO3DZ_DESPECLE_KY	Value of despecleKy is invalid.
ERR_NANO3DZ_BG_SUB_KY	Value of bgSubKy is invalid.
ERR_NANO3DZ_LASER_THR	Value of laserThr is invalid.
ERR_NANO3DZ_LASER_DYMIN	Value of laserDyMin is invalid.
ERR_NANO3DZ_LASER_DYMAX	Value of laserDyMax is invalid.
ERR_NANO3DZ_LASER_SEL	Value of laserSelect is invalid.
ERR_NANO3DZ_LASER_SEL_NR	Value of laserSelectNr is invalid.
ERR_NANO3DZ_LASER_DYOPT	Value of laserDyOpt is invalid.

Function Documentation

vc_nano3dz_external_mapper_toMM()

I32 vc_nano3dz_external_mapper_toMM

(

VCCaptCfg *

cpt

)

This function calculates Nano3D-Z result pixel data of the laser line to world MM data and sets the mmIff1 to 1. It is done for each sensor at the cpt struct.

• sets cpt->sen[*].c.nano3dz->result.mmX[*]
• sets cpt->sen[*].c.nano3dz->result.mmZ[*]
• sets cpt->sen[*].c.nano3dz->result.mmIff1 = 1

The mapper is loaded at initialisation of the sensor, for example during the call of the function vc_cam_init(), and unloaded, if the sensor is completely deinitialized.

Parameters

cpt	Call changes: cpt->sen[*].c.nano3dz->result

Return values

>0	if some values could not be transformed,
0	on success,
<0	on error, especially ERR_MODEL if mapper is not available.

vc_nano3dz_external_mapper_toMM_()

I32 vc_nano3dz_external_mapper_toMM_	(	F32 *	xPX,
		F32 *	yPX,
		F32 *	xMM,
		F32 *	yMM,
		I32	cnt,
		struct _VCNano3dZMappers *	mappers
	)

This function calculates Nano3D-Z result pixel data of the laser line to world MM data by transforming the array-like lists xPx and yPx to their output values at xMM and yMM.

The mapper information for the Nano3D-Z is stored at VCSenCfg ->c.nano3dz->cfg.d.e.mappers, you can use the macro vc_nano3dz_external_mapper_toMM_F32F32() for convenience instead of this function.

Parameters

xPX,yPX	List of values to be transformed.
xMM,zMM	List of result values.
cnt	Entries at lists xPx, yPx, xMM and yMM.
mappers	see Text.

Return values

0	on success,
<0	on error.

See also

vc_nano3dz_external_mapper_toMM_F32F32(), vc_nano3dz_external_mapper_toMM(), vc_nano3dz_external_mapper_toPX().

vc_nano3dz_external_mapper_toPX_()

I32 vc_nano3dz_external_mapper_toPX_	(	F32 *	xMM,
		F32 *	yMM,
		F32 *	xPX,
		F32 *	yPX,
		I32	cnt,
		struct _VCNano3dZMappers *	mappers
	)

This function calculates Nano3D-Z result world MM data of the laser line to pixel data by transforming the array-like lists xMM and yMM to their output values at xPx and yPx.

The mapper information for the Nano3D-Z is stored at VCSenCfg ->c.nano3dz->cfg.d.e.mappers, you can use the macro vc_nano3dz_external_mapper_toMM_F32F32() for convenience instead of this function.

Parameters

xMM,zMM	List of values to be transformed.
xPX,yPX	List of result values.
cnt	Entries at lists xPx, yPx, xMM and yMM.
mappers	see Text.

Return values

>0	if some values could not be transformed,
0	on success,
<0	on error.

See also

vc_nano3dz_external_mapper_toPX(), vc_nano3dz_external_mapper_toMM_F32F32(), vc_nano3dz_external_mapper_toMM().