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:

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 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().

VC nano3D-Z

Data Structures

Detailed Description

Data Structure Documentation

◆ VCNano3dZResult

◆ VCNano3dZInit

◆ VCNano3dZVolatile

◆ VCNano3dZExternal

◆ VCNano3dZDesc

◆ VCNano3dZCfg

◆ VCNano3dZ

Macro Definition Documentation

◆ VCNano3dZInit_Default

◆ str_VCErrNano3dZ

◆ vc_nano3dz_laser_switch

◆ vc_nano3dz_external_mapper_toMM_F32F32

◆ vc_nano3dz_external_mapper_toPX

◆ VCSenCustomCalls_Nano3dZ

Enumeration Type Documentation

◆ VCNano3dZSelect

◆ VCErrNano3dZ

Function Documentation

◆ vc_nano3dz_external_mapper_toMM()

◆ vc_nano3dz_external_mapper_toMM_()

◆ vc_nano3dz_external_mapper_toPX_()