ScanCnf

The ScanCnf object supports the interfaces:

bstrType [IScanCnf]

SYNOPSIS
BSTR bstrMy;
bstrMy = bstrType;

REMARKS
bstrType is a read only variable that holds a string that describes the type of instrument. This string is valid after Open returned SCFN_OPEN. (The value of the string usually is the value that can be retrieved by the .#VI command.)

SEE ALSO
Open


bstrSerialNumber [IScanCnf3]

SYNOPSIS
BSTR bstrMy;
bstrMy = bstrSerialNumber;

REMARKS
bstrSerialNumber is a read only variable that holds a string that is the serial number of the instrument. This string is valid after Open returned SCFN_OPEN. (The value of the string usually is the value that can be retrieved by the .#SN command.)

SEE ALSO
Open


dPhi, dDeltaPhi, nlNumPhi,
dTheta, dDeltaTheta, nlNumTheta
[IScanCnf]

SYNOPSIS
double dPhiMy;
dPhiMy = dPhi;
dPhi = dPhiMy;
double dDeltaPhiMyPhi;
dDeltaPhi = dDeltaPhi;
dDeltaPhi = dDeltaPhiMy;
long int nlNumPhiMy;
nlNumPhiMy = nlNumPhi;
nlNumPhi = nlNumPhiMy;
double dThetaMy;
dThetaMy = dTheta;
dTheta = dThetaMy;
double dDeltaThetaMy;
dDeltaThetaMy = dDeltaTheta;
dDeltaTheta = dDeltaThetaMy;
long int nlNumThetaMy;
nlNumThetaMy = nlNumTheta;
nlNumTheta = nlNumThetaMy;

REMARKS

These read/write variables are the main scanner state parameters. The Phi angle corresponds to scanner head movement (usually horizontal) while Theta corresponds to mirror movement (usually vertical). You specify a starting angle (where the first line is to be taken), a number of measurements and an angle increment for each measurement line. The last measuement is at angle Start + (Number-1)*Increment.
After the scanner port has been opened these variables are initialized with the current scanner state. You can safely access them after you have received the SCFN_OPEN message.
To change the scanner state you simply write new values to these variables and issue the Apply() command. If the Apply() is not successful you will need to modify some or all of the parameters, before you can successfully apply them to the instrument. The library aids you in this process by means of the Calc() function.
All angle parameters are in units of degree (0° ... 360°).
There are some special values available to control the scanner head: (not vailable on all models)
Setting nlNumPhi to zero.
This will put the scanner in a line scan mode.
Setting nlNumPhi and nlNumTheta to zero.
This will put the scanner in a single point measurement mode, without positioning. This is useful when used together with a joystick.
The dPhi, dDeltaPhi and nlNumPhi have no meaning for 2D-scanner types.
You simply should not modify them. If you do, they will be reset to default values when doing a "Calc".

SEE ALSO
Open, Apply, Calc


dClock [IScanCnf]

SYNOPSIS
double dClockMy;
dClockMy = dClock;
dClock = dClockMy;

REMARKS
This variable is your means to influence measurement rate. It is equivalent to the peak 'laser-frequency'. It is subject to a number of constraints such as eye-safety requirements or minimum mirror speed. Please note that to obtain the total time of measurement it is not sufficient to multiply the time requirement for a single shot (e.g dClock) by the total number of points (nlNumPhi * nlNumTheta), since the measurements are not evenly distributed over the complete rotation of the mirror wheel. The remaining pause accounts for an additional time proportional to the number of total rotations needed for an entire scan.
dClock will be activated through isuue of the Apply() command. If the Apply fails, you can use the Calc() command to get assistance to get applicable values.
One useful application would be to get fastest possible operation. To this end, you would specify all the scanner angles and then set the rate to a high value i.e 30000. Then you will call Calc() to have the library adjust the variables and follow with Apply() to activate the settings.
An other useful application would be to lower the measurement rate such as to accomodate the requirements of a slower transmission network.
The unit of dClock is [Hz].

SEE ALSO
Open, Apply, Calc


nMotion [IScanCnf]

SYNOPSIS
int nMotionMy;
nMotionMy = nMotion;
nMotion = SCF_MOTION_SINGLE_UNIDIRECTIONAL;
nMotion = SCF_MOTION_SINGLE_BIDIRECTIONAL;
nMotion = SCF_MOTION_CONTINUOUS;

REMARKS
The nMotion variable controls the scanning head movements. It is valid after a succesful Open() of the scanner. After changing it's value you have to Apply() and/or Calc() as in the case of the other variables. Please note that single frame mode is not compatible with all open modes of the Scanner library. You will need to specify an OpenEx() call in this case.

SEE ALSO
Apply, Calc


dTotalTime [IScanCnf]

SYNOPSIS
double dTotalTimeMy;
dTotalTimeMy = dTotalTime;

REMARKS
This is a read only variable that holds a estimate of the total time needed for the acquisition of an entire frame. The value 0.0 means that no estimate is available. Please note that the estimate might be wrong since the laser did not yet choose its operating mode. However after having applied your settings this variable should reflect a valid estimate.
The unit of dTotalTime is [s].

SEE ALSO
Open, Apply, Calc


dTemperature [IScanCnf3]

SYNOPSIS
double dTemperatureMy;
dTemperatureMy = dTemperature;

REMARKS
This is a read only variable that reflects the temperature of the instrument at the time the connection was opened.
The unit of dTemperature is [Celsius].

SEE ALSO
Open


dSupplyVoltage [IScanCnf3]

SYNOPSIS
double dSupplyVoltageMy;
dSupplyVoltageMy = dTemperature;

REMARKS
This is a read only variable that reflects the operating voltage of the instrument at the time the connection was opened.
The unit of dSupplyVoltage is [V].

SEE ALSO
Open


nlOperatingTime [IScanCnf3]

SYNOPSIS
long nlOperatingTimeMy;
nlOperatingTimeMy = nlOperatingTime;

REMARKS
This is a read only variable that reflects the total operating time of the instrument at the time the connection was opened.
The unit of nlOperatingTime is [s].

SEE ALSO
Open


nlLaserTime [IScanCnf3]

SYNOPSIS
long nlLaserTimeMy;
nlLaserTimeMy = nlLaserTime;

REMARKS
This is a read only variable that reflects the total operating time of the laser at the time the connection was opened.
The unit of nlLaserTime is [s].

SEE ALSO
Open


nlScanTime [IScanCnf3]

SYNOPSIS
long nlScanTimeMy;
nlScanTimeMy = nlScanTime;

REMARKS
This is a read only variable that reflects the total operating time of the scanner mechanics at the time the connection was opened.
The unit of nlScanTime is [s].

SEE ALSO
Open


Open [IScanCnf]

SYNOPSIS
Open( BSTR bstrPort, DWORD hWnd, UINT uMsg, WORD wId);

MESSAGES
SCFN_OPEN signals the success of the operation.

PARAMETERS
bstrPort
The port name is one of the following:
\\.\COM1:19200 specifiy the serial port. In this example COM1 with 19200 Baud
//hostname:servicename on all platforms to establish a TCP/IP connection
hWnd
The windows handle of a window that will receive messages. No messages are sent if set to zero, and any calls that normally would generate messages are synchronous.
uMsg
Specify the value of the windows message you want to receive. Usually this will be WM_USER, but you are free to use any other value in case it interferes with your software. (WM_USER is defined as the numerical value of 1024 in the system header files of windows.)
wId
Specify an Id value that is unique to this connection. You can use this to have a single window handle messages that come from differemt connections. The messages received at the window specified with hWnd are in the form wParam = HIWORD(MESSAGE), LOWORD(wId).

REMARKS
Open will try to establish a connection directly to the scanner. Device names start with the sequence \\.\ followed by the name of the device, which is COM followed by a numerical identifier of the respective port.
Network names start with the sequence //. You may omit the host and service names in which case a default of ib90eth:scancmd will be used. The mapping between hostnames and IP addresses will depend on the network setup of your machine, as is the mapping between service name and port numbers. (Usually they are defined in the hosts and services files.) It is possible however to directly specify an IP address / port number pair e.g. 192.168.11.222:20001, in which case there is no need for hosts and services files.

As soon as you have opened the connection, a window identified by hWnd, will receive messages specified by uMsg. The messages are further identified by a windows wParam and lParam parameter. The HIWORD(wParam) contains the scanner messages as defined in this document. The LOWORD(wParam) contains the Id value you have specified in the call to Open. The lParam contains message specific information such as error number.

You should not assume the connection being open before you have received the SCN_OPEN message.

If you specify 0 for the hWnd parameter, no messages are generated, and the Open, Close, Apply and Calc calls will wait until the operation has been completed. This mode is useful, if you do not have a window handle, e.g. when calling from a console application or from a worker thread. However, you will block your current thread, and so it is not recommended for GUI threads. You should avoid calling other functions while one of the pending operations is in progress, since this will result in errors. Also an end of file condition will be reported as an error in this case.

When you are finished using the port you will need to close the connection.

If you are using the native interface to the scanner you also will need to call the Open funtion before.

SEE ALSO
Close


Close [IScanCnf]

SYNOPSIS
Close( );

MESSAGES
SCFN_CLOSE

PARAMETERS
none

REMARKS
After you are finished using the port you will need to close it to free its resources and reenable for further open calls. Once closed, none of the other functions will succeed. You should not assume the close operation to have finished before you receive the SCFN_CLOSE message.

SEE ALSO
Open


Apply [IScanCnf]

SYNOPSIS
Apply( );

MESSAGES
SCFN_APPLYsignals the sucessful application of settings

PARAMETERS
none

REMARKS
The key parameters of the scanner (dPhi, dDeltaPhi, nlNumPhi, dTheta, dDeltaTheta, nlNumTheta, dClock) have a nontrivial interdependence. As there is no simple formula that can describe this interdependence, it is checked when you issue the Apply() call. If your requested settings would result in a violation of maximum or minimum motor speeds, or contradict eye-safety rules, the Apply() will fail. You then have the option to supply a different set of parameters based on some knowledge of your own or have the library suggest you a set of parameters that will fit your original parameters as close as possible, while still satisfying the constraints of the scanner head.

SEE ALSO
Calc


Calc [IScanCnf]

SYNOPSIS
Calc( );

MESSAGES
SCFN_CALCCalculation has been finished.

PARAMETERS
none

REMARKS
As has been mentioned in the REMARKS section of Apply() the primary scanner parameters are interdependent in a nontrivial manner. During Apply() the constraints, that have to be fullfilled are checked and if cannot be met need to be adjusted by you. The Calc() function helps you in doing that. It tries to find as close as possible to your original parameters, that meet the constraints.
The algorithm used has the following goals:
You could routinely call Calc() after you have set the parameters and before calling Apply(), but you should be aware, that the parameters may differ from the original supplied set. So you should read back the final values and show them to the user, so as to inform him/she what is the actual state of the scanner.

SEE ALSO
Apply


ChooseScanArea [IScanCnf3]

SYNOPSIS
ChooseScanArea( BSTR bstrReflectorType, float dOverlapping, unsigned uCoordSystem, float* rgPos);

MESSAGES
none

PARAMETERS
bstrReflectorType
Describes the reflector type... Following types are available:
A - Any type .... e.g. A0.15 (all reflector types until 0.15m)
C - Circle ...... e.g. C0.15 (a round reflector with a diameter of 0.15m )
R - Rectangle ... e.g. R0.15,0.25 (a rectangular reflector with 0.15m width and 0.25m height)
dOverlapping
Overlapping factor (1.0 .. 100.0)
uCoordSystem
An unsigned value that specifies the coordinaten system: either SCF_CARTESIAN or SCF_POLAR.
rgPos
Pointer to a float array, which describes the (approximate) position of the reflector.
This should be X, Y, Z or Range, Theta, Phi

REMARKS
The ChooseScanArea function should be used to prepare a high resolution "reflector" scan. You will need to supply information such as the size of the refector and the approximate distance to the reflector. Based on this input an optimized scan pattern will be choosen. For the approximate reflector position you should take a value that e.g. has been obtained from a coarse scan of the scene. But you also can use information from external sources of course. The overlapping controls the total density of laser-shots that will cover the reflector. Higher values imply denser coverage. Currently the type of reflector is mostly insignificant. The only information that is beeing used, is its size. It is sufficient to specify "A0.2" if you want to scan a reflector of 20 cm (largest diameter).
NOTE: You should call Calc after you have set the parameters with this function.
SEE ALSO
none


GetErrNmb [IScanCnf]

SYNOPSIS
GetErrNmb( int* pnError );

MESSAGES
none

PARAMETERS
pnError
Pointer to an integer variable that will receive the error number

REMARKS
Typically you will need to call this function in response to an error message (SCFN_ERROR). The library has a sticky error behaviour. e.g. the first error is locked until you call this fuction, which resets the error condition.
If the number you get from GetErrNmb is equal to the lParam value that you have received with the SCFN_ERROR message there have been no additional errors.
You should prepare your application to be able to receive error messages after you have called the Open function.

Currently the following error codes are defined:
SCF_ERROR_NOERROR No error
SCF_ERROR_CANNOT_OPEN Cannot open
SCF_ERROR_CANNOT_READ Cannot read
SCF_ERROR_NOMEM Cannot allocate memory
SCF_ERROR_EDOM Argument out of function's domain
SCF_ERROR_ASYNC_CALL Unexpected behaviour, likely related to async call
SCF_ERROR_BAD_APPLY Apply failed
SCF_ERROR_UNKNOWN Unknow error reason
SCF_ERROR_DEMO_MODE Requested operation is not licensed
SCF_ERROR_SCANNER Scanner dependent error, more info in GetErrStr

SEE ALSO
GetErrStr


GetErrStr [IScanCnf]

SYNOPSIS
GetErrStr( int nError, BSTR* pbstrError );

MESSAGES
none

PARAMETERS
nError
The error number, for which you want the string representation.
pbstrError
A human readable string representation of the error.

REMARKS
This function fills in a BSTR with a human readable string representation of the error. This string is suitable for display in a message box or similar to give visual feedback to the user. This function may be called at any time, i.e. it does not reset the error system. In other terms this means you may not omit a call to GetErrNmb to reset the error. The strings are stored in a windows resource that is located in scannermod.dll and therefore automatic language conversion will take place when possible.
Translation will not occur for SCF_ERROR_SCANNER, since this error string is retrieved directly from the instrument. This string also may change or even be empty depending on the current state of the scanning device.

SEE ALSO
GetErrNmb


dBeamFocus, dBeamDivergence, dBeamAperture [IScanCnf2]

SYNOPSIS
double dBeamFocusMy;
dBeamFocusMy = dBeamFocus;
dBeamFocus = dBeamFocusMy;
double dBeamDivergenceMy;
dBeamDivergenceMy = dBeamDivergence;
dBeamDivergence = dBeamDivergenceMy;
double dBeamApertureMy;
dBeamApertureMy = dBeamAperture;
dBeamAperture = dBeamApertureMy;

REMARKS
These read/write variables give Information on the laser-beam geometry of the scanner. Please note, that the variables might not be writeable, as your instrument does not support the requested change. In this case the Apply() will fail.
After the scanner port has been opened these variables are initialized with the current scanner state. You can safely access them after you have received the SCFN_OPEN message.
To change the scanner state you simply write new values to these variables and issue the Apply() command. If the Apply() is not successful you will need to modify some or all of the parameters, before you can successfully apply them to the instrument. The library aids you in this process by means of the Calc() function.

SEE ALSO
Open, Apply, Calc


nMode [IScanCnf2]

SYNOPSIS
nMode = SCF_MODE_POLARSCAN;
nMode = SCF_MODE_USTSCAN;

REMARKS
This variable chooses the main operation mode of the scanner. SCF_MODE_POLARSCAN is the standard angular-pattern scan mode. This also is the default mode when using the IScanCnf interface. To activate the user-defined mode you have to use the IScanCnf2 interface specify SCF_MODE_USTSCAN, and be connected to a scanner that supports this mode. Please note, that the angular scan parameters are of no meaning in this case.
The UST scan-pattern is made up of up to nlRows measurements per scan-line. A total of nlColumns scan lines defines a whole scan-frame. This is similar to the angular measurement mode. The difference is in the fact, that in UST mode you can specify the positions where measurements are to be taken.
In angular mode a scan-line is defined by a vertical only movement of the scanner head. The UST mode employs simultaneous movement of both directions, and therefore is able to follow straight lines or arbitrary paths.
The data from the resulting frame can be fetched by means of the GetVertex() call of the IScanner interface in the usual manner.
Since it might be desirable to specify a scan frame that consists of scan lines of different lengths, you have the option of specifying dummy measurements to make the total length of all lines equal. To this end you either let Apply() append dummy measurements behind every scan line, or you specify an offset to your scanline to prepend dummy measurements. This procedure will not have an effect on the total number of measurements, but only on the position within the GetVertex(). If you are planning to filter out invalid measurements before calling GetVertex it does not make sense to specify any offsets since these measurement will be filtered off anyway.

SEE ALSO
SetLine, SetPolyLine, SetSkewedPlane, Open, Apply, Calc


nlRows, nlColumns [IScanCnf2]

SYNOPSIS
long int nlRowsMy;
nlRowsMy = nlRows;
nlRows = nlRowsMy;
long int nlColumnsMy;
nlColumnsMy = nlColumns;
nlColumns = nlColumnsMy;

REMARKS
These read/write variables control the Userdefined Scan Trace. The Rows Parameter specifies the measurements within a scan-line, while Columns specifies the number of scan-lines that make up a frame. Please note, that if you specify inapropriate sizes, you still may use the Calc() function to calculate the tightest row/cols for your scan-pattern.
Example: specify 0 for both parameters and call Calc() after you have set your pattern.
After the scanner port has been opened these variables are initialized with the current scanner state. You can safely access them after you have received the SCFN_OPEN message.
To change the scanner state you simply write new values to these variables and issue the Apply() command. If the Apply() is not successful you will need to modify some or all of the parameters, before you can successfully apply them to the instrument. The library aids you in this process by means of the Calc() function.

SEE ALSO
SetLine, SetPolyLine, SetSkewedPlane, Open, Apply, Calc


SetPolyLine [IScanCnf2]

SYNOPSIS
SetPolyLine( unsigned uType, int nColumn, int nOffset, float rgVertex[], int nCount);

MESSAGES
none

PARAMETERS
uType
SCF_CARTESIAN, SCF_POLAR, or SCF_POLAR_MATH
nColumn
specifies the number of the resulting scan-line
nOffset
specifies an additional offset within the resulting scan-line
rgVertex
the 3-d path the scanner will follow
nCount
the number of vertices in rgVertex

REMARKS This function is the most flexible way to specify a scan-line. You have to supply it with an array of 3-d points, that specifies a scan trace. This virtual path is converted to the 2-d angular space of the scanner head from which an appropriate motor controling sequence is generated then. This line makes up the nColumn`t line of the entire frame. Please note, that the resulting measurement data that can be retrieved by means of the GetVertex() call later does not necessarily expose the usual point neighbourhood since you can specify arbitrary paths with this function.

SEE ALSO
nMode SetLine, SetPolyLine, SetSkewedPlane, Apply, s


SetLine [IScanCnf2]

SYNOPSIS
SetLine( unsigned uType, int nColumn, int nOffset, float dDelta, float rgA[], float rgB[]);

MESSAGES
none

PARAMETERS
uType
SCF_CARTESIAN, SCF_POLAR, or SCF_POLAR_MATH
nColumn
specifies the number of the resulting scan-line
nOffset
specifies an additional offset within the resulting scan-line
dDelta
specifies the increment between laser shots (in [m]).
rgA, rgB>
the 3-d start and ending points of the line

REMARKS
This specifies a straight line between rgA and rgB, spaced by dDelta. Since it is inconvenient to calculate the resulting number of measurements (nlRows) before calling this function, it is recommended to use the Calc() function after the entire scan pattern has been specified.

SEE ALSO
nMode


SetSkewedPlane [IScanCnf2]

SYNOPSIS
SetSkewedPlane( unsigned uType, float rgA[], float rgB[], float rgC[], float rgD[]);

MESSAGES
none

PARAMETERS
uType
SCF_CARTESIAN, SCF_POLAR, or SCF_POLAR_MATH
rgA, rgB, rgC, rgD
the 3-d corner points of the skewed plane

REMARKS
This function can be used to specify a complete scan-frame by specifying four 3-d corner points. The scan lines all consist of nlRows measurements, and the total number of lines is nlColumns. This also means that you need to set nlRows and nlColumns accordingly before. The first trace is between rgA and rgB and the last trace between rgC and rgD. All offsets in the resulting scan-frame are set to zero.

SEE ALSO
nMode