Conventions

Each of the objects may support multiple interfaces. The RiSCANLIB uses this to extend the interfaces in a compatible manner. When a newer version of the library adds functions to an interface, thereby extending it, the new interface gets an ever incremnted number appended. e.g. Version 1 : IScanner, Version 2 : IScanner2, ...
In the documentation only the newest interface will appear. This does not mean, that you cannot use older Interfaces on newer libraries. The opposite is true. You are even encouraged to use the interface, that has the least number of functions you really need. This way you achieve the largest compatibility.

The documentation of each function will show at which version it has been introduced. e.g.

Foo [IFace5]

means, that the Foo function has been introduced at Version 5 of the interface, or that if you need this function you at least must make sure that the system has a COM object installed, that supports Version 5 of the interface at minimum.

Scanner

The Scanner object supports the interfaces:

Open [IScanner]

SYNOPSIS
Open( BSTR bstrDevice, BSTR bstrLogFile, DWORD hWnd, UINT uMsgType, UINT uMsg);

MESSAGES
SCN_OPEN signals the success of the operation.

PARAMETERS
bstrDevice
The device name is either a regular disk file name or one of the following:
\\.\RiPT0 on Windows NT (Windows 2000) to access the device driver
\\.\ECP0 on Windows 95/98 to directly access the port hardware in ECP mode
\\.\LPT0 on Windows 95/98 to directly access the port hardware in bidirectional mode
//hostname:servicename on all platforms to establish a TCP/IP connection
bstrLogFile
Specify any legal disk file name to enable data logging. (An empty string disables logging.)
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.
uMsgType
Any combination of the following constants: (binary or'ed or arithmetic sum)
SCN_MFRAMESTART to enable the SCN_FRAMESTART message.
SCN_MLINE to enable the SCN_LINE message.
SCN_MFRAME to enable the SCN_FRAME message.
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.)

REMARKS
Open will try to establish a connection either to a disk file or directly to the scanner. Disk files are opened with read sharing allowed, whereas device connections allow only one connection at the same time.
Device names start with the sequence \\.\ followed by the name of the device, which may be one of RIPT ECP LPT followed by a numerical identifier of the respective port. On Windows NT/2000 you specify the mapping between this number and the port hardware in the driver settings of RiPort device driver. On Windows 95/98 (where no device driver is used) the number 0 corresponds to address 0x378 (LPT1) and number 1 to address 0x278 (LPT2). Please note: since on the Windows 95/98 platform no device driver is used, there is the potetial of resource conflicts when accessing the port. Also the processor load will be rather high since no interrupts are used and the port has to be polled constantly. So you should either use the Windows 2000 platform or consider using a IB90ETH network unit.
Network names start with the sequence //. You may omit the host and service names in which case a default of ib90eth:scandata 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 wParam contains the scanner messages as defined in this document. The lParam contains message specific information such as current line number, frame number or error number. You have some control on the messages sent to your window by specifying the uMsgType parameter: Specifying the respective constants selects the respective messages to be sent. E.g. to enable a message on frame start and one on the end of the frame you would specify SCN_MFRAMESTART | SCN_MFRAME (assuming you are using the C programming language).

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 and NextFrame 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 not be able to access the internal buffer before a complete frame has been read in. You shoul 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 file or device you will need to close the connection.

SEE ALSO
Close, Log


OpenEx [IScanner]

SYNOPSIS
OpenEx( BSTR bstrDevice, BSTR bstrCmd, BSTR bstrLogFile, DWORD hWnd, UINT uMsgType, UINT uMsg, WORD wId);

MESSAGES
SCN_OPEN signals the success of the operation.

PARAMETERS
bstrDevice
The device name is either a regular disk file name or one of the following:
\\.\RiPT0 on Windows NT (Windows 2000) to access the device driver
\\.\ECP0 on Windows 95/98 to directly access the port hardware in ECP mode
\\.\LPT0 on Windows 95/98 to directly access the port hardware in bidirectional mode
\\.\COM1:19200 specifiy the serial port. In this example COM1 with 19200 Baud
//hostname:servicename on all platforms to establish a TCP/IP connection
bstrCmd
The Command port, one of the following:
(Required for some scanner types for full control.)
\\.\COM1:19200 specifiy the serial port. In this example COM1 with 19200 Baud
//hostname:servicename on all platforms to establish a TCP/IP connection to the command port.
bstrLogFile
Specify any legal disk file name to enable data logging. (An empty string disables logging.)
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.
uMsgType
Any combination of the following constants: (binary or'ed or arithmetic sum)
SCN_MFRAMESTART to enable the SCN_FRAMESTART message.
SCN_MLINE to enable the SCN_LINE message.
SCN_MFRAME to enable the SCN_FRAME message.
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
If wId is set to zero (compatible mode) the behaviour is exactly as with the normal open function. When not equal to zero, the messages received at the window specified with hWnd are in the form wParam = HIWORD(MESSAGE), LOWORD(wId).
In compatible mode this is sent as wParam = HIWORD(0), LOWORD(MESSAGE). You can use this to have one window handling messages from multiple scanner sources, each of which is identified by wId.

REMARKS
OpenEx is an extended version of Open. The following additional features are available:
You can specifiy a command port. Using a command port you can operate the scanning head in single frame mode.
You may specify an Id value. This can be used to have one window receiving messages from multiple concurrently open scanner sources.

SEE ALSO
Close, Log


Close [IScanner]

SYNOPSIS
Close( );

MESSAGES
SCN_CLOSE

PARAMETERS
none

REMARKS
After you are finished using the device or file you will need to close it to free its resources and reenable for further open calls. Once closed, none of the data access function will succeed. You should not assume the close operation to have finished before you receive the SCN_CLOSE message.

If you specified a log file in open, the logfile will also be closed with this command.

SEE ALSO
Open, Log


Log [IScanner]

SYNOPSIS
Log( int nOn );

MESSAGES
SCN_LOGSTARTEDsignals the actual start of logging
SCN_LOGSTOPPEDlogging has stopped

PARAMETERS
nOn
Controls the logging state. Set this parameter to 0 (or FALSE) when you want to pause logging. To reenable logging set to 1 (or TRUE).

REMARKS
The scanner library allows automatic logging of the binary data stream to a disk file. The filename is specified using the Open command. Logging does not start instantly but waits for the start of a frame. Then the message SCN_LOGSTARTED is sent. Logging continues till either you specify the nOn to be FALSE in a further call to Log(FALSE) or close the connection. However in the first case the logging will stop on a succesfully received frame i.e in sync with a SCN_FRAME message, whereas in the second the log will close after the last successully received scan line. When logging actually stops you will receive a SCN_LOGSTOPPED message.

SEE ALSO
Open, Close


NextFrame [IScanner]

SYNOPSIS
NextFrame( );

MESSAGES
SCN_FRAMESTARTlParam: FrameNumbersignals start of a frame.
SCN_LINElParam: LineNumbersignals receipt of a line.
SCN_FRAMElParam: FrameNumbersignals end of a frame
SCN_EOFsignals end of file condition (applies to disk files)

PARAMETERS
none

REMARKS
Calling NextFrame instructs the library to begin filling its internal framebuffer. You will receive notification messages about the progress. SCN_FRAMESTART is beeing sent when the start of a frame is detected. SCN_LINE is beeing sent on each received line, and SCN_FRAME is sent at the end of the frame. Filling of the buffer automatically stops at this point. To acquire the following frame another NextFrame call is required.
The SCN_FRAMESTART message not necessarily is the first message you will receive after a NextFrame call. There may be a couple of SCN_LINE messages before the begin of a frame is detected. You could make use of this to get a 'life' display of the current scanning head activity. However it is guaranteed, that the SCN_FRAMESTART message comes before any SCN_LINE messages belonging to the respective frame. Also the SCN_FRAME message is beeing sent after the last SCN_LINE of the respective frame.
Typically you will react on one or all of the messages and call a data access function to obtain vertex, color or intensity information. To this end you will need to read the message parameters indicating line or frame numbers. The line number can be used in a data access function to address the respective line. Although you can use any line number at any time, only line numbers that have been received by SCN_LINE messages contain valid data. All others retreive data having range set to zero (or SetInfinity).
The SCN_EOF message relates to the physical end of disk files. On receipt of this messages no further NextFrame calls will be possible. However the data buffer contains valid data up to the line where this message has been received.

SEE ALSO
SetInfinity, GetDimension, GetVertex, GetRGB, GetIntensity, GetRawInfo, GetRawHeader, GetRawData


Pause [IScanner]

SYNOPSIS
Pause( );

MESSAGES
none

PARAMETERS
none

REMARKS
Call this function to temporarily suspend data acquisition. A second call will cause data acquisition to continue. This function acts as a toggle switch. If you are not sure about the current state, you also can use NextFrame to continue acquisition unconditionally.

SEE ALSO


SetMode [IScanner]

SYNOPSIS
SetMode( int nSetMode);

MESSAGES
none

PARAMETERS
nSetMode
SCN_MODE_FILTER_NOTARGET
SCN_MODE_COLOR_NATIVE
SCN_MODE_COLOR_CONTRAST

REMARKS
The SetMode command affects the operational mode of the library.
When SCN_MODE_FILTER_NOTARGET is specified the data retrieval functions return only measurement points that correspond to a valid target. You would specify this option if you need point clouds with illegal points removed. Note however, that the rectangualar grid structure of the scandata is destroyed, when using this option. The Get* functions will report the actual returned number of points via the pnTransferred parameter.
SCN_MODE_COLOR_NATIVE and SCN_MODE_COLOR_CONTRAST influence the operation of the GetRGB call. The first causes unprocessed data to be delivered while the second prerocesses data to enhace the contrast of the image. Contrast enhancement also is the default mode.

SEE ALSO
ReSetMode, GetVertex, GetRGB, GetIntensity GetStdDev, GetTime,


ReSetMode [IScanner]

SYNOPSIS
ReSetMode( int nReSetMode);

MESSAGES
none

PARAMETERS
nReSetMode
Currently only SCN_MODE_FILTER_NOTARGET available.

REMARKS
This option reverts the respective SetMode calls.

SEE ALSO
SetMode


SetInfinity [IScanner]

SYNOPSIS
SetInfinity( double dInfinity);

MESSAGES
none

PARAMETERS
dInfinity
Set the range associated with invalid points.

REMARKS
When the scanner could not successfully acquire range data at a distinctive point, e.g poor reflectivity, excessive range, a means is needed to signal this condition. The default is to set range to zero. This also applies to cartesian data where x,y,z coordinates are zero at the same time. But there are reasons when this is not acceptable. Consider the case when measuring to the sky, which obviously is far beyond the specified range capability of the scanner. The scanner still records color and angle information in that case. So to get this data you would specify a infinity range that is beyond all of your objects. Now when you read data in cartesian coordinates this point will read out as beeing located on a sphere with radius dInfinity.
Data in the frame buffer that are beeing accessed before any SCN_LINE messages have been received all are marked as invalid points and as such are retrieved as lying on this sphere.

SEE ALSO


SetPPM [IScanner3]

SYNOPSIS
SetPPM( double dAtmospheric, double dGeometric);

MESSAGES
none

PARAMETERS
dAtmospheric
Set the atmospheric PPM correction value. Zero if not set explicitely.
dGeometric
Set the geometric PPM correction value. Zero if not set explicitely.

REMARKS
The atmospheric PPM correction is applied to the measured range distance, before the scanner specific correction.
The geometric PPM correction value is a linear isotropic scaling of the resulting measurement points, relative to the local origin of the scanning head.
(A value of x PPM is applied as a factor of 1 + x * 10exp-6 )

SEE ALSO


GetDimension [IScanner]

SYNOPSIS
GetDimension( int *pnLinesPerImage, int *pnMeasPerLine );

MESSAGES
none

PARAMETERS
pnLinesPerImage
Pointer to an integer variable that will receive the number of lines that make a frame.
pnMeasPerLine
Pointer to an integer variable that will receive the number of measurements (i.e. single points) that make a line.

REMARKS
pnLinesPerImage and pnMeasPerLine are pointers to variables that receive the number of lines and measurements per line respectively.
The internal data buffer is arranged as a two dimensional grid. The first index (the faster one) refers to the point number of a single measurement. A total of *pnMeasPerLine data points make a line of the frame. The second (slower) index refers to the line number. The entire frame consists of *pnLinesperImage lines. You may however address the data buffer in a different manner, namely as a single huge one dimensional array (or any part of it). This single array has a total size of *pnLinesperImage times *pnMeasPerLine.
To retreive data you will need to specify a start index and a number of data points you want to receive.
Example:
Let N be the number of measurements per line
and M be the number of lines per image.
In order to retreive the m'th line you would specify m•N as the start index and N as the number of points you want to receive in your call.
Or to receive the entire point cloud in a single call you would specify 0 for the start index and M•N for the number of points to retrieve.

SEE ALSO
GetVertex, GetRGB, GetIntensity


GetMatrix [IScanner]

SYNOPSIS
GetMatrix( double* pdlMatrix);

MESSAGES
none

PARAMETERS
pdlMatrix
Pointer to an array of 16 double values that will receive the transformation matrix.

REMARKS
The scanner data may have an attached transformation matrix, e.g to have muliple scans registered into a common coordinate system. This transformation matrix usually can be set within the scanner by specifying 3 angles and 3 translation vectors. (See the manual of your scanning device.)
When using the GetVertex call the transformation is applied by default. (See also GetVertex to obtain local coordinates.)
The GetMatrix call retrieves the transformation matrix. You might do this to get the scanner position, or to do the transformation in the application program. The latter would be necessary when you have large transformation offset values. In that case a floating value might have not enough precision to hold the transformed data. (GetVertex retrieves only float values.)
The transformed values obey the following formula, where Mi are the values of pdlMatrix, yi are the transformed and xi are the local coordinates as retrieved by GetVertex.
y0 = M0*x0 + M4*x1 + M8*x2 + M12
y1 = M1*x0 + M5*x1 + M9*x2 + M13
y2 = M2*x0 + M6*x1 + M10*x2 + M14
If the scanner does not have a transformation matrix or if it is not set, the matrix is unity.
NOTE: The transformation matrix is used to convert from the scanner coordinate system to a project coordinate system. (It should not be used for transformation to a global system.)

SEE ALSO
GetVertex,


GetVertex [IScanner]

SYNOPSIS
GetVertex( int* pnTransfered, float rgVertex[], unsigned uType, int nSize, int nStart, int nCount );

MESSAGES
none

PARAMETERS
pnTransfered
Pointer to an integer variable that will receive the number of actually transfered vertices.
rgVertex
Pointer to a float array that will receive the vertex data.
uType
An unsigned value that specifies the type: either SCN_CARTESIAN or SCN_POLAR.
(Optionally combined with SCN_LOCAL).
nSize
An integer value that specifies the dimesionality of a vertex: 1, 2, or 3
nStart
An integer value that specifies the start into the internal frame buffer (GetDimesion).
nCount
An integer value that specifies the number of vertices to retrieve (GetDimesion).

REMARKS
The GetVertex call retrieves geometry data from the internal buffer and performs polar to cartesian conversion. (specified by SCN_CARTESIAN or SCN_POLAR) The scanner data might optionally be offset (and rotated) by a coordinate transform. You will receive data with this transform already applied. If you do not want the data to be transformed you need to combine the type code with SCN_LOCAL, which retrieves the vertex data in the scanners local coordinate system. E.g.: SCN_LOCAL|SCN_CARTESIAN to retrieve local cartesian coordinates. This internal buffer is formatted in the binary format of the respective scanner type. Depending on this type there might be 3-D, 2-D or 1-D information available. Despite this fact it is always possible to retrieve data in any dimensionality. In cases where you request a higher dimension, than the device provides, the missing coordinates are filled with constant values. This is done in such a way that provides a consistent coordinate system. Requesting lower dimensionality than the unit is capable of, results in elimination of some coordinates:
The total motion of a 3-D scanner is associated with two angles, the first (polar angle J) is related to the movement of the mirror, the second (azimuth angle j) is related to the motion of the head. Requesting 2-D data results in neglection of the azimuth angle. A similar approach is taken in case of 2-D (or 3-D) to 1-D downconversion: Neglection of the mirror movement, resulting in a single geometric information, namely the range.
Table 1 summarizes the various parameter combinations for the vertex call. Table 2 displays the formulas used for polar (spherical) to cartesian conversion.

You further have to provide a pointer to a floating point array of nSize•nCount elements. The GetVertex call tries to fill in nCount vertices, but stops, should you try to request elements beyond the end of the buffer. The count of actually transfered items is returned via a variable that pnTransfered is pointing to. The elements of the returned vertex array are ordered according to Table 1. E.g. x1, y1, z1, x2, y2, z2, x3, ...

Distances all are in units of meter. Angles are in radian.

[Table 1] Dimension conversion table
GetVertex Instrument dimensionality
nSizeuType 1-D 2-D 3-D
1 SCN_POLAR ( r ) ( r ) ( r )
SCN_CARTESIAN ( x ) ( x'' ) ( x'' )
2 SCN_POLAR ( r, p/2 ) ( r, J ) ( r, J )
SCN_CARTESIAN ( x, 0 ) ( x, z ) ( x', z )
3 SCN_POLAR ( r, 0, p/2 ) ( r, 0, J ) ( r, j, J )
SCN_CARTESIAN ( x, 0, 0 ) ( x, 0, z ) ( x, y, z )
[Table 2] Polar to cartesian conversion formulas
x=r•cos(j)•sin(J)
x'=r•sin(J)
x''=r
y=r•sin(j)•sin(J)
z=r•cos(J)
If you supply NULL for the rgVertex parameter you, the call will process as normal, but without returning any data. In particular the pnTransfered will reflect the correct amount. You may use this to obtain the number of memory needed when you apply the SCN_MODE_FILTER_NOTARGET mode.

SEE ALSO
GetDimension, GetRGB, GetIntensity, GetTime


GetStdDev [IScanner]

SYNOPSIS
GetStdDev( int* pnTransfered, float rgStdDev[], int nSize, int nStart, int nCount );

MESSAGES
none

PARAMETERS
pnTransfered
Pointer to an integer variable that will receive the number of actually transfered values.
rgStdDev
Pointer to a float array that will receive the std deviation data.
nSize
An integer value that specifies the number of values: currently only 1 for range available
nStart
An integer value that specifies the start into the internal frame buffer (GetDimesion).
nCount
An integer value that specifies the number of values to retrieve (GetDimesion).

REMARKS
The GetStdDev call retrieves standard deviation values for the range (and angle) measurement from the internal buffer. You have to provide a pointer to a floating point array of nSize•nCount elements. The GetStdDev call tries to fill in nCount values, but stops, should you try to request elements beyond the end of the buffer. The count of actually transfered items is returned via a variable that pnTransfered is pointing to.
Standard deviation of range is in units of meter. Standard deviation of Angles are in radian.
If you supply NULL for the rgStdDev parameter you, the call will process as normal, but without returning any data. In particular the pnTransfered will reflect the correct amount. You may use this to obtain the number of memory needed when you apply the SCN_MODE_FILTER_NOTARGET mode.

SEE ALSO
GetDimension, GetVertex, GetRGB, GetIntensity, GetTime


GetIntensity [IScanner]

SYNOPSIS
GetIntensity( int* pnTransfered, float rgIntensity[], int nStart, int nCount );

MESSAGES
none

PARAMETERS
pnTransfered
Pointer to an integer variable that will receive the numer of actually transfered intensity values.
rgIntensity
Pointer to a float array that will receive the intensity data.
nStart
An integer value that specifies the start into the internal frame buffer (GetDimesion).
nCount
An integer value that specifies the number of intensity values to retrieve (GetDimesion).

REMARKS
You will need to provide a pointer to a floating point array of nCount elements. The GetIntensity call tries to fill in nCount intensity values, but stops, should you try to request elements beyond the end of the buffer. The count of actually transfered items is returned via a variable that pnTransfered is pointing to.
Intensity values are in the range 0.0 to 1.0. They relate to strength of the reflected laser beam.
If you supply NULL for the rgIntensityparameter you, the call will process as normal, but without returning any data. In particular the pnTransfered will reflect the correct amount. You may use this to obtain the number of memory needed when you apply the SCN_MODE_FILTER_NOTARGET mode.

SEE ALSO
GetDimension, GetRGB, GetVertex, GetTime


GetRGB [IScanner]

SYNOPSIS
GetRGB( int* pnTransfered, float rgRGB[], int nStart, int nCount );

MESSAGES
none

PARAMETERS
pnTransfered
Pointer to an integer variable that will receive the numer of actually transfered RGB values.
rgRGB
Pointer to a float array that will receive the RGB data.
nStart
An integer value that specifies the start into the internal frame buffer (GetDimesion).
nCount
An integer value that specifies the number of RGB values to retrieve (GetDimesion).

REMARKS
You will need to provide a pointer to a floating point array of 3•nCount elements. The GetRGB call tries to fill in nCount RGB values, but stops, should you try to request elements beyond the end of the buffer. The count of actually transfered items is returned via a variable that pnTransfered is pointing to.
RGB values are in the range 0.0 to 1.0. They are returned in triplets in sequence Red1, Green1, Blue1, Red2, ....
The library preprocesses RGB data by default. (Also see: SetMode) You can switch off this behaviour to obtain native data if desired.
If you supply NULL for the rgRGB parameter you, the call will process as normal, but without returning any data. In particular the pnTransfered will reflect the correct amount. You may use this to obtain the number of memory needed when you apply the SCN_MODE_FILTER_NOTARGET mode.

SEE ALSO
GetDimension, GetVertex, GetIntensity, GetTime, SetMode


GetTime [IScanner]

SYNOPSIS
GetTime( int* pnTransfered, DWORD rgTime[], int nStart, int nCount );

MESSAGES
none

pnTransfered
Pointer to an integer variable that will receive the numer of actually transfered time values.
rgTime
Pointer to a DWORD (32bit) array that will receive the time data.
nStart
An integer value that specifies the start into the internal frame buffer (GetDimesion).
nCount
An integer value that specifies the number of time values to retrieve (GetDimesion).

REMARKS
You will need to provide a pointer to a DWORD array of nCount elements. The GetTime call tries to fill in nCount time values, but stops, should you try to request elements beyond the end of the buffer. The count of actually transfered items is returned via a variable that pnTransfered is pointing to.
Time values are not measured in physical units. You will need to refer to the respective manual of the device to understand their meaning.
If you supply NULL for the rgTime parameter you, the call will process as normal, but without returning any data. In particular the pnTransfered will reflect the correct amount. You may use this to obtain the number of memory needed when you apply the SCN_MODE_FILTER_NOTARGET mode.

SEE ALSO
GetDimension, GetVertex, GetIntensity, GetRGB


GetTimeEx [IScanner4]

SYNOPSIS
GetTimeEx( int* pnTransfered, double rgTime[], int nStart, int nCount );

MESSAGES
none

pnTransfered
Pointer to an integer variable that will receive the numer of actually transfered time values.
rgTime
Pointer to a double (64bit) array that will receive the time data.
nStart
An integer value that specifies the start into the internal frame buffer (GetDimesion).
nCount
An integer value that specifies the number of time values to retrieve (GetDimesion).

REMARKS
You will need to provide a pointer to a double array of nCount elements. The GetTime call tries to fill in nCount time values, but stops, should you try to request elements beyond the end of the buffer. The count of actually transfered items is returned via a variable that pnTransfered is pointing to.
Time values retrieved by this function are measured in seconds. Please also review the SetEpoch function for further explanation.
If the scanner does not supply extended timestamping e.g. only line timestamps, or unsynchronized timestamps, this function delivers the equivalent of the GetTime function, but correctly scaled to units of second. You will need to consult your scanner manual to find out which support of time stamping is available.
If you supply NULL for the rgTime parameter you, the call will process as normal, but without returning any data. In particular the pnTransfered will reflect the correct amount. You may use this to obtain the number of memory needed when you apply the SCN_MODE_FILTER_NOTARGET mode.

SEE ALSO
SetEpoch,
bstrSyncTime,
bstrSyncMode,
bstrEpoch,


GetRawInfo [IScanner]

SYNOPSIS
GetRawInfo( BOOL* pfValid, int* pnHeaderSize, int* pnLineSize, int* pnLines );

MESSAGES
none

PARAMETERS
pfValid
Pointer to a boolean variable signalling success.
pnHeaderSize
Pointer to an integer variable that will receive the size of the header in bytes.
pnLineSize
Pointer to an integer variable that will receive the size of a data line in bytes.
pnLines
Pointer to an integer variable that will receive the number of lines.

REMARKS
GetRawInfo is a helper function for GetRawHeader and GetRawData. This values are the nCount parameters you should specify in calls to these functions.

SEE ALSO
GetRawHeader, GetRawData


GetRawHeader [IScanner]

SYNOPSIS
GetRawHeader( int* pnCount, BYTE* pbHeader, int nCount );

MESSAGES
none

pnCount
Pointer to an integer variable that will receive the number of actually transfered bytes.
pbHeader
Pointer to a buffer of byte values.
nCount
An integer value that specifies the number of bytes to retrieve (GetRawInfo).

REMARKS
This function retrieves the raw header as it is received from the scanning device. You supply a buffer into which the header data is beeing copied. You will need to consult the manual of your scanner device to interpret the data.
It is not necessary, although possible to use this function for data logging, since the library has a built in data log facility (see Log).

SEE ALSO
GetRawInfo, GetRawData


GetRawData [IScanner]

SYNOPSIS
GetRawData( int* pnCount, int nLine, BYTE* pbData, int nCount );

MESSAGES
none

PARAMETERS
pnCount
Pointer to an integer variable that will receive the number of actually transfered bytes.
nLine
The line number for which you want to retrieve data.
pbData
Pointer to a buffer of byte values.
nCount
An integer value that specifies the number of bytes to retrieve (GetRawInfo).

REMARKS
This function retrieves the raw data for a line as it is received from the scanning device. You supply a buffer into which the data is beeing copied. You will need to consult the manual of your scanner device to interpret the data.
It is not necessary, although possible to use this function for data logging, since the library has a built in data log facility (see Log).
Please note, that the raw data obtained this way is not directly comparable to what you get when you specify SCN_POLAR in the GetVertex call, since there are scanner dependent corrections necessary to get true spherical data.

SEE ALSO
GetRawInfo, GetRawHeader


GetErrNmb [IScanner]

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 (SCN_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 SCN_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:
SCN_ERROR_NOERROR No error
SCN_ERROR_CANNOT_OPEN Cannot open
SCN_ERROR_CANNOT_READ Cannot read
SCN_ERROR_UNKNOWN_HEADER_ID Unknown header ID
SCN_ERROR_UNKNOWN_TRAILER_IDUnknown trailer ID
SCN_ERROR_UNKNOWN_MEAS_ID Unknown measurement ID
SCN_ERROR_UNKNOWN_PARM_ID Unknown parameter ID
SCN_ERROR_NOMEM Cannot allocate memory
SCN_ERROR_SYNC_LOST Synchronization lost
SCN_ERROR_NODATA No data
SCN_ERROR_EDOM Argument out of function's domain
SCN_ERROR_CREATE_LOG Could not create log file
SCN_ERROR_DEMO_MODE Requested operation is not licensed
SCN_ERROR_EOF End of file
SCN_ERROR_ASYNC_CALL Unexpected behaviour, likely related to async call

SEE ALSO
GetErrStr


GetErrStr [IScanner]

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.

SEE ALSO
GetErrNmb


GetTriangles [IScanner2]

SYNOPSIS
GetTriangles( int* pnTransfered, UINT rgTriangles[], unsigned uType, int nCount);


PARAMETERS
pnTransfered
Pointer to an integer variable that will receive the number of actually transfered triangles.
rgTriangles
Pointer to a UINT array that will receive the triangle data.
uType
An unsigned value that specifies the type: currently only SCN_SIMPLE.
nCount
An integer value that specifies the number of triangles to retrieve (specifies the supplied buffer size).

REMARKS
GetTriangles retrieves triangle geometry data. The information is retrieved as an array of indices that point into the array of vertex data. The index 0 is aligned to the vertex array in the following manner: When you retrieve vertexdata with nStart=0, the index 0 relates correctly to the vertex array. You must be careful, when retrieving data with different nStart values.
The triangle data is organized into an array of triplets: indexA1, indexB1, indexC1, indexA2, ... where A,B,C constitute a single triangle, which has an orientation that is oriented counter clockwise.
The function assumes that you supply a buffer that is 3*uCount*sizeof(UINT). To get the needed buffersize in advance you may call the function with rgnTriangles=NULL. pnTransfered will return the total number of triangles available. However this method is slower, than supplying a buffer of size uCount=2*(nLinesPerImage-1)*(nMeasPerLine-1), and then throwing away the excess memory.

The SCN_SIMPLE type specifies a very simple triangle generation method. It uses neigbouring information that is trivially available from the basic mesh, that results from the scanning geometry. A "jump" detection filter removes triangles that have connection points that are too far apart, and therefore most likely do not belong to the same object.

The GetTriangles function is influenced by the SCN_FILTER_NOTARGET mode. The indices are correct within either mode.

SEE ALSO
GetDimension, GetVertex


SetEpoch [IScanner4]

SYNOPSIS
SetEpoch( BSTR bstrEpoch);


PARAMETERS
bstrEpoch
Specify a new epoch for the GetTimeEx call.

REMARKS
SetEpoch will set the epoch for the following GetTimeEx calls. Time as retrieved by GetTimeEx is the amount of seconds since the Epoch. The internal clock of the scanner records the time instances of the laser shots with respect to the last time this clock has been synchronized to some reference clock. You can offset this internal timestamp data to any point in time. This is called the Epoch. The default value of the epoch after the Open call is set to 00:00:00 of the date the internal clock last has been synchronized.
The IScanInfo interface gives you access to the sync-time and current setting of the epoch as well. The format of the epoch string is:
YYYY-MM-DDTHH:MM:SS
e.g.: 2005-12-20T13:05:02 specifies the 20'th december 2005 1:05:02 pm.
Please note that the date must be a valid gregorian date, else the internal algorithm will calculate a wrong offset to the sync-time.

SEE ALSO
GetTimeEx,
GetTime
bstrSyncTime,
bstrSyncMode,
bstrEpoch,