OceanDirect  2.4.0
OceanDirect C++/C API
oceandirect::api::OceanDirectAPI Class Reference

Public Member Functions

int addNetworkDevice (const char *ipAddressStr, const char *deviceTypeStr, int *errorCode)
 
void addRS232DeviceLocation (char *deviceTypeName, char *deviceBusPath, unsigned int baud, int *errorCode)
 
AdvanceAdvancedControl ()
 
void applyElectricDarkCorrection (long deviceID, int *errorCode, bool value)
 
void applyNonLinearityCorrection (long deviceID, int *errorCode, bool value)
 
void boxcarCorrectSpectrum (long deviceID, int *errorCode, double *illuminatedSpectrum, unsigned int illuminatedSpectrumLength, unsigned int boxcarWidth)
 
void closeDevice (long deviceID, int *errorCode)
 
int darkCorrectSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
int darkCorrectSpectrum (long deviceID, int *errorCode, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
int detectNetworkDevices ()
 
bool electricDarkCorrectionUsage (long deviceID, int *errorCode)
 
void getAPIRCNumber (unsigned int *candidate)
 
double getAPIVersionNumber ()
 
void getAPIVersionNumber (unsigned int *major, unsigned int *minor, unsigned int *point)
 
unsigned short int getBoxcarWidth (long deviceID, int *errorCode)
 
int getDarkCorrectedSpectrum (long deviceID, int *errorCode, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
int getDarkCorrectedSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
unsigned long getDelayIncrementMicroseconds (long deviceID, int *errorCode)
 
unsigned long getDelayMaximumMicroseconds (long deviceID, int *errorCode)
 
unsigned long getDelayMicroseconds (long deviceID, int *errorCode)
 
unsigned long getDelayMinimumMicroseconds (long deviceID, int *errorCode)
 
IDevice * getDeviceByID (unsigned long id)
 
unsigned char getDeviceEndpoint (long deviceID, int *error_code, usbEndpointType endpointType)
 
int getDeviceIDs (long *ids, unsigned long maxLength)
 
int getDeviceModelText (long deviceID, int *errorCode, char *buffer, unsigned int bufferLength)
 
int getDeviceType (long deviceID, int *errorCode, char *buffer, unsigned int length)
 
int getElectricDarkPixelCount (long deviceID, int *errorCode)
 
int getElectricDarkPixelIndices (long deviceID, int *errorCode, int *indices, int length)
 
int getErrorMessage (int errorCode, char *returnMessage, int length)
 
int getErrorStringLength (int errorCode)
 
int getFormattedSpectrum (long deviceID, int *errorCode, double *buffer, int bufferLength)
 
int getFormattedSpectrumLength (long deviceID, int *errorCode)
 
int getIndexAtWavelength (long deviceID, int *errorCode, double &wavelength, double approxWavelength)
 
int getIndicesAtAnyWavelength (long deviceID, int *errorCode, int *indices, int indicesLength, double *wavelength, int wavelengthLength)
 
int getIndicesAtWavelengthRange (long deviceID, int *errorCode, int *indices, int indicesLength, double *wavelengthLength, int wavelengthSize, double lo, double hi)
 
unsigned long getIntegrationTimeIncrementMicros (long deviceID, int *errorCode)
 
unsigned long getIntegrationTimeMicros (long deviceID, int *errorCode)
 
unsigned long getMaximumIntegrationTimeMicros (long deviceID, int *errorCode)
 
double getMaximumIntensity (long deviceID, int *errorCode)
 
unsigned long getMinimumAveragingIntegrationTimeMicros (long deviceID, int *errorCode)
 
unsigned long getMinimumIntegrationTimeMicros (long deviceID, int *errorCode)
 
int getNetworkDeviceIDs (long *ids, unsigned long maxLength)
 
int getNonlinearityCorrectedSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
int getNonlinearityCorrectedSpectrum (long deviceID, int *errorCode, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
int getNumberOfDeviceIDs ()
 
int getRawSpectrumWithMetadata (long deviceID, int *errorCode, SpectrumWithMetadata *buffer, int bufferLength)
 
unsigned int getScansToAverage (long deviceID, int *errorCode)
 
int getSerialNumber (long deviceID, int *errorCode, char *buffer, int bufferLength)
 
unsigned char getSerialNumberMaximumLength (long deviceID, int *errorCode)
 
int getStoredDarkSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength)
 
long long int getTime (long deviceID, int *errorCode)
 
int getTriggerMode (long deviceID, int *errorCode)
 
int getWavelengthCoefficients (long deviceID, int *errorCode, double *coeff, int length)
 
int getWavelengths (long deviceID, int *errorCode, double *wavelengths, int length)
 
bool isFeatureEnabled (long deviceId, int *errorCode, FeatureId featureId)
 
bool nonLinearityCorrectionUsage (long deviceID, int *errorCode)
 
int nonlinearityCorrectSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
int nonlinearityCorrectSpectrum (long deviceID, int *errorCode, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
void openDevice (long deviceID, int *errorCode)
 
int probeDevices ()
 
void setBoxcarWidth (long deviceID, int *errorCode, unsigned short int boxcarWidth)
 
void setDelayMicroseconds (long deviceID, int *errorCode, unsigned long delayMicroseconds)
 
void setIntegrationTimeMicros (long deviceID, int *errorCode, unsigned long integrationTimeMicros)
 
void setScansToAverage (long deviceID, int *errorCode, unsigned int scansToAverage)
 
void setStoredDarkSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength)
 
void setTime (long deviceID, int *errorCode, long long int timeInMicrosecond)
 
void setTriggerMode (long deviceID, int *errorCode, int mode)
 

Static Public Member Functions

static OceanDirectAPIgetInstance ()
 
static void shutdown ()
 

Friends

class NetOceanDirectAdmin
 
class OceanDirectAdminAPI
 

Member Function Documentation

◆ addNetworkDevice()

int oceandirect::api::OceanDirectAPI::addNetworkDevice ( const char *  ipAddressStr,
const char *  deviceTypeStr,
int *  errorCode 
)

Manually create an instance of the network attached device and then open it using the openDevice() function. It is the responsiblitiy of the user to ensure that the device exists and is configured properly. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
ipAddressStrThe ip address as string (ex: "10.20.30.100" ) of the device to be opened.
deviceTypeStrThe device type could be OceanFX or OceanHDX. This is case sensitive.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist;
Returns
The device id or -1 if an error occured.

◆ addRS232DeviceLocation()

void oceandirect::api::OceanDirectAPI::addRS232DeviceLocation ( char *  deviceTypeName,
char *  deviceBusPath,
unsigned int  baud,
int *  errorCode 
)

Use the addRS232DeviceLocation() method to specify that a device may be found on a particular serial bus with a given baud rate. Once specified, the typical openDevice() function can be used to access it.

Parameters
deviceTypeNamea valid Ocean spectrometer device type.
deviceBusPatha valid serial port path that the device is connected to.
baudthe baud rate for the specified serial port.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_INVALID_ARGUMENT if the device cannot be created.

◆ AdvancedControl()

Advance* oceandirect::api::OceanDirectAPI::AdvancedControl ( )

Advanced extension of the API. Access to the advanced APIs is throught the pointer returned by this function.

Returns
a pointer to access the advanced APIs.

◆ applyElectricDarkCorrection()

void oceandirect::api::OceanDirectAPI::applyElectricDarkCorrection ( long  deviceID,
int *  errorCode,
bool  value 
)
Deprecated:
Use electric dark correction on the acquired spectra.
See also
setStoredDarkSpectrum
getStoredDarkSpectrum
getDarkCorrectedSpectrum
Warning
if electric dark correction is enabled using this function then some of the newer dark correction functionality e.g. getDarkCorrectedSpectrum may not be used.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.

◆ applyNonLinearityCorrection()

void oceandirect::api::OceanDirectAPI::applyNonLinearityCorrection ( long  deviceID,
int *  errorCode,
bool  value 
)
Deprecated:
Set nonlinearity correction on or off on raw spectrum
See also
setStoredDarkSpectrum
getStoredDarkSpectrum
getNonlinearityCorrectedSpectrum
Warning
if nonlinearity correction is enabled using this function then some of the newer nonlinearity correction functionality e.g. getNonlinearityCorrectedSpectrum may not be used.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.
valuetrue if nonlinearity correction is to be used, false otherwise.

◆ boxcarCorrectSpectrum()

void oceandirect::api::OceanDirectAPI::boxcarCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  illuminatedSpectrum,
unsigned int  illuminatedSpectrumLength,
unsigned int  boxcarWidth 
)

Apply a boxcar correction on the given illuminated spectrum.

Parameters
[in]deviceIDThe identifier of the device as returned by getDeviceIDs.
[out]errorCodeSet to 0 if successful, an OceanDirect error code (nonzero) otherwise ERROR_VALUE_NOT_FOUND no stored dark spectrum was found; ERROR_NO_DEVICE if deviceID is not a valid and open deviceID ERROR_TRANSFER_ERROR if a communication error occurred ERROR_FEATURE_NOT_FOUND if device does not support this feature ERROR_COMMAND_NOT_SUPPORTED if device does not support this command.
[in/out]illuminatedSpectrum The spectrum that will be boxcar corrected.
[in]boxcarWidthThe boxcar width.

◆ closeDevice()

void oceandirect::api::OceanDirectAPI::closeDevice ( long  deviceID,
int *  errorCode 
)

This will attempt to close the bus connection to the device with the given ID. The id becomes invalid after closing the device. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.

◆ darkCorrectSpectrum() [1/2]

int oceandirect::api::OceanDirectAPI::darkCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)

Dark correct a previously acquired illuminated spectrum using a previously acquired dark spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success;
darkSpectrumthe buffer that contains the dark spectrum to be used for the dark correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ darkCorrectSpectrum() [2/2]

int oceandirect::api::OceanDirectAPI::darkCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)

Dark correct a previously acquired illuminated spectrum using a stored dark spectrum.

See also
setStoredDarkSpectrum
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ detectNetworkDevices()

int oceandirect::api::OceanDirectAPI::detectNetworkDevices ( )

This provides a way to find all Ethernet discoverable devices on a network. Afterwards, a call to probeDevices is neccessary to grab the interface for opening and connecting to discovered device. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Returns
the number of detected network devices.

◆ electricDarkCorrectionUsage()

bool oceandirect::api::OceanDirectAPI::electricDarkCorrectionUsage ( long  deviceID,
int *  errorCode 
)
Deprecated:
Determine if electric dark correction to the acquired spectra is on or off.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.
Returns
true if electric dark correction is turned on, false if electric dark correction is either turned off or is not supported (see the returned error code).

◆ getAPIVersionNumber() [1/2]

double oceandirect::api::OceanDirectAPI::getAPIVersionNumber ( )
Deprecated:
Get OceanDirect software release version number (Note: There is a new version numbering scheme including a point release. This function will only report the major and minor version number).
See also
getAPIVersionNumber

◆ getAPIVersionNumber() [2/2]

void oceandirect::api::OceanDirectAPI::getAPIVersionNumber ( unsigned int *  major,
unsigned int *  minor,
unsigned int *  point 
)

Return the major, minor and point release version numbers.

Parameters
majorthe major software version number.
minorthe minor software version number.
pointthe point software version number.

◆ getBoxcarWidth()

unsigned short int oceandirect::api::OceanDirectAPI::getBoxcarWidth ( long  deviceID,
int *  errorCode 
)

Get the width of the boxcar smoothing to be applied to the returned spectrum. When this value has been set greater than 0, boxcar smoothing (a moving average) is applied to the spectrum returned by getFormattedSpectrum (or getRawSpectrumWithMetadata). The width specified is the number of pixels either side of the central pixel of the average i.e. if the result of this function is n, the "full width" of the smoothing is 2*n+1.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the width of the smoothing to be applied per returned spectrum.

◆ getDarkCorrectedSpectrum() [1/2]

int oceandirect::api::OceanDirectAPI::getDarkCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)

Acquire a spectrum and use the previously stored dark spectrum to perform a dark correction then return the dark corrected spectrum.

See also
setStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found. ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getDarkCorrectedSpectrum() [2/2]

int oceandirect::api::OceanDirectAPI::getDarkCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)

Acquire a spectrum and use the supplied dark spectrum to perform a dark correction then return the dark corrected spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be used for the dark correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getDelayIncrementMicroseconds()

unsigned long oceandirect::api::OceanDirectAPI::getDelayIncrementMicroseconds ( long  deviceID,
int *  errorCode 
)

Get the acquisition delay period increment in microseconds. The increment is the minimum difference (in microseconds) between two adjacent, valid acquisition delay periods.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the acquisition delay period increment in microseconds.

◆ getDelayMaximumMicroseconds()

unsigned long oceandirect::api::OceanDirectAPI::getDelayMaximumMicroseconds ( long  deviceID,
int *  errorCode 
)

Get the maximum valid acquisition delay period in microseconds.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum acquisition delay period in microseconds.

◆ getDelayMicroseconds()

unsigned long oceandirect::api::OceanDirectAPI::getDelayMicroseconds ( long  deviceID,
int *  errorCode 
)

Get the acquisition delay period in microseconds.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the acquisition delay period in microseconds.

◆ getDelayMinimumMicroseconds()

unsigned long oceandirect::api::OceanDirectAPI::getDelayMinimumMicroseconds ( long  deviceID,
int *  errorCode 
)

Get the minimum valid acquisition delay period in microseconds.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the minimum acquisition delay period in microseconds.

◆ getDeviceEndpoint()

unsigned char oceandirect::api::OceanDirectAPI::getDeviceEndpoint ( long  deviceID,
int *  error_code,
usbEndpointType  endpointType 
)

Get the usb endpoint address for a specified type of endpoint

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_INPUT_OUT_OF_BOUNDS if an invalid endpoint value is supplied; ERROR_NO_DEVICE if the device does not exist.
endpointTypethe USB endpoint type (see UsbEndpoint.h)
Returns
the endpoint address for the requested endpoint.

◆ getDeviceIDs()

int oceandirect::api::OceanDirectAPI::getDeviceIDs ( long *  ids,
unsigned long  maxLength 
)

This provides a unique ID of each device that is detected or specified. The IDs are copied into the user-provided buffer. These IDs are weak references: attempting to access a device that no longer exists will cause an error value to be returned but should not cause any instability. The IDs may be entirely random, but a given ID will always refer to the same device for as long as the program is running. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
idsthe buffer to receive the device IDs.
maxLengththe actual size of the buffer ids.
Returns
the number of device IDs actually copied into the array or 0 on error.

◆ getDeviceModelText()

int oceandirect::api::OceanDirectAPI::getDeviceModelText ( long  deviceID,
int *  errorCode,
char *  buffer,
unsigned int  bufferLength 
)

Get the device model name by passing in a pre-allocated buffer

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the feature is not available; ERROR_NO_DEVICE if the device does not exist.
buffera character buffer to receive the device model string.
bufferLengththe length of the supplied buffer.
Returns
the actual length of the device model string on success.

◆ getDeviceType()

int oceandirect::api::OceanDirectAPI::getDeviceType ( long  deviceID,
int *  errorCode,
char *  buffer,
unsigned int  length 
)

Get a string that describes the type of device

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_BAD_USER_BUFFER if the pointer to the buffer is null or the supplied buffer length is 0; ERROR_NO_DEVICE if the device does not exist.
buffera character buffer to receive the device type string.
lengththe length of the supplied buffer.
Returns
the actual length of the device type string on success.

◆ getElectricDarkPixelCount()

int oceandirect::api::OceanDirectAPI::getElectricDarkPixelCount ( long  deviceID,
int *  errorCode 
)

Get electric dark pixel count

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.
Returns
the number of electric dark pixels or zero if the electric dark correction is not supported (see the returned error code).

◆ getElectricDarkPixelIndices()

int oceandirect::api::OceanDirectAPI::getElectricDarkPixelIndices ( long  deviceID,
int *  errorCode,
int *  indices,
int  length 
)

Get electric dark pixel indices.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.
indicesthe buffer that will receive the indices of the electric dark pixels.
lengththe actual size of the buffer.
Returns
the number of electric dark pixels copied into the buffer or zero if the electric dark correction is not supported (see the returned error code).

◆ getErrorMessage()

int oceandirect::api::OceanDirectAPI::getErrorMessage ( int  errorCode,
char *  returnMessage,
int  length 
)

Get error message associated with the given error code. If the error code is incorrect then the return message will be "Error. Undefined error".

Parameters
errorCodeThe error code.
returnMessageThe output buffer.
lengthOutput buffer length
Returns
The number of characters copied into the output buffer.

◆ getErrorStringLength()

int oceandirect::api::OceanDirectAPI::getErrorStringLength ( int  errorCode)

Get error message length associated with the given error code. If the error code is incorrect then the return message length will be 0.

Parameters
errorCodeThe error code.
Returns
The number of characters copied into the output buffer.

◆ getFormattedSpectrum()

int oceandirect::api::OceanDirectAPI::getFormattedSpectrum ( long  deviceID,
int *  errorCode,
double *  buffer,
int  bufferLength 
)

Get a formatted spectrum

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NOT_ENOUGH_BUFFER_SPACE if the size of the buffer is smaller than the formatted spectrum length; ERROR_NO_DEVICE if the device does not exist.
bufferthe buffer that will receive the formatted spectrum.
bufferLengththe actual size of the buffer.
Returns
the actual number of pixels copied into buffer.

◆ getFormattedSpectrumLength()

int oceandirect::api::OceanDirectAPI::getFormattedSpectrumLength ( long  deviceID,
int *  errorCode 
)

Get formatted spectrum length i.e. the number of pixels in the spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the size of the formatted spectrum.

◆ getIndexAtWavelength()

int oceandirect::api::OceanDirectAPI::getIndexAtWavelength ( long  deviceID,
int *  errorCode,
double &  wavelength,
double  approxWavelength 
)

Get wavelength closest to the specified approximate wavelength.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_ARRAY_INDEX_OUT_OF_BOUNDS the specified wavelengths is not within the device's wavelength range; ERROR_NO_DEVICE if the device does not exist.
wavelengththe wavelength of the pixel nearest to the approximate wavelength within the device's wavelength range.
approxWavelengththe approximate wavelength of the desired pixel to be found.
Returns
the index of the pixel closest to the approximate wavelength on success, -1 otherwise.

◆ getIndicesAtAnyWavelength()

int oceandirect::api::OceanDirectAPI::getIndicesAtAnyWavelength ( long  deviceID,
int *  errorCode,
int *  indices,
int  indicesLength,
double *  wavelength,
int  wavelengthLength 
)

Get the indices and actual wavelengths of a specified set of wavelengths.

Note
if any of the specified wavelengths are out of bounds then the wavelengths array may be partially overwritten with the actual wavelengths found up to the point when the error occurred.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_ARRAY_INDEX_OUT_OF_BOUNDS one or more of the specified wavelengths is not within the device's wavelength range; ERROR_NO_DEVICE if the device does not exist.
indicesThe buffer that will receive the indices of the pixels associated with the specified wavelengths.
indicesLengthThe indices buffer size.
wavelengthThe wavelengths to be searched for, overwritten with the actual wavelengths found.
wavelengthLengthThe wavelength buffer size.
lengththe actual length of the array of wavelengths to be searched for.
Returns
the number of pixel indices copied into the buffer.

◆ getIndicesAtWavelengthRange()

int oceandirect::api::OceanDirectAPI::getIndicesAtWavelengthRange ( long  deviceID,
int *  errorCode,
int *  indices,
int  indicesLength,
double *  wavelengthLength,
int  wavelengthSize,
double  lo,
double  hi 
)

Get wavelength indices within a specified wavelength range

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_ARRAY_INDEX_OUT_OF_BOUNDS the lower or upper bound specified is not within the device's wavelength range;
ERROR_NO_DEVICE if the device does not exist.
indicesThe output buffer that will receive the indices of the pixels in the specified range.
indicesLengthThe indices buffer size.
wavelengthThe output buffer that will receive the wavelengths associated with each pixel index.
wavelengthLengthThe wavelength buffer size.
lothe lower bound of the wavelength range.
hithe upper bound of the wavelength range.
Returns
the number of pixel indices copied into the buffer.

◆ getInstance()

static OceanDirectAPI* oceandirect::api::OceanDirectAPI::getInstance ( )
static

No public constructor. To use this class in C++, you must first call getInstance(). This provides a singleton: it is the same on every call.

Parameters
licenseStatusreturns 0 on success i.e. there is a valid software license, 1 otherwise in which case Ocean should be contacted.

◆ getIntegrationTimeIncrementMicros()

unsigned long oceandirect::api::OceanDirectAPI::getIntegrationTimeIncrementMicros ( long  deviceID,
int *  errorCode 
)

Get integration time increment in microseconds

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INPUT_OUT_OF_BOUNDS if an invalid integration time is supplied; ERROR_NO_DEVICE if the device does not exist.
Returns
the integration time increment in microseconds.

◆ getIntegrationTimeMicros()

unsigned long oceandirect::api::OceanDirectAPI::getIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)

Get integration time in microseconds

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INPUT_OUT_OF_BOUNDS if an invalid integration time is supplied; ERROR_NO_DEVICE if the device does not exist.
Returns
the integration time in microseconds.

◆ getMaximumIntegrationTimeMicros()

unsigned long oceandirect::api::OceanDirectAPI::getMaximumIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)

Get maximum integration time in microseconds

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum integration time in microseconds.

◆ getMaximumIntensity()

double oceandirect::api::OceanDirectAPI::getMaximumIntensity ( long  deviceID,
int *  errorCode 
)

Get max intensity (in raw counts) that can be returned in any pixel.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum pixel intensity.

◆ getMinimumAveragingIntegrationTimeMicros()

unsigned long oceandirect::api::OceanDirectAPI::getMinimumAveragingIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)

Get minimum integration time in microseconds when averaging is enabled.

Note
some devices that make use of onboard functionality to perform averaging have a different, larger, minimum integration time for acquisition when averaging is enabled. Refer to the documentation for your spectrometer to see if this is the case. The minimum integration time when averaging is not enabled can be determined using getMinimumIntegrationTimeMicros.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the minimum integration time in microseconds with averaging enabled.

◆ getMinimumIntegrationTimeMicros()

unsigned long oceandirect::api::OceanDirectAPI::getMinimumIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)

Get minimum integration time in microseconds.

Note
some devices that make use of onboard functionality to perform averaging have a different, larger, minimum integration time for acquisition when averaging is enabled. Refer to the documentation for your spectrometer to see if this is the case. The minimum integration time when averaging is enabled can be determined using getMinimumAveragingIntegrationTimeMicros.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the minimum integration time in microseconds for acquisition with no averaging.

◆ getNetworkDeviceIDs()

int oceandirect::api::OceanDirectAPI::getNetworkDeviceIDs ( long *  ids,
unsigned long  maxLength 
)

This provides a unique ID of each network attached device that is detected or manually specified. The IDs are copied into the user-provided buffer. These IDs are weak references: attempting to access a device that no longer exists will cause an error value to be returned but should not cause any instability. The IDs may be entirely random, but a given ID will always refer to the same device for as long as the program is running. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
idsthe buffer to receive the device IDs.
maxLengththe actual size of the buffer ids.
Returns
the number of device IDs actually copied into the array or 0 on error.

◆ getNonlinearityCorrectedSpectrum() [1/2]

int oceandirect::api::OceanDirectAPI::getNonlinearityCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)

Acquire a spectrum and use the supplied dark spectrum to perform a dark correction followed by the nonlinearity correction then return the nonlinearity corrected spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be used for the dark correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getNonlinearityCorrectedSpectrum() [2/2]

int oceandirect::api::OceanDirectAPI::getNonlinearityCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)

Acquire a spectrum and use the previously stored dark spectrum to perform a dark correction followed by a nonlinearity correction then return the nonlinearity corrected spectrum.

See also
setStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getNumberOfDeviceIDs()

int oceandirect::api::OceanDirectAPI::getNumberOfDeviceIDs ( )

This provides the number of devices that have either been probed or manually specified. Devices are not opened automatically, but this can provide a bound for getDeviceIDs(). Note that this should only be done by one thread at a time.

Returns
the total number of devices, both specified and probed.

◆ getRawSpectrumWithMetadata()

int oceandirect::api::OceanDirectAPI::getRawSpectrumWithMetadata ( long  deviceID,
int *  errorCode,
SpectrumWithMetadata *  buffer,
int  bufferLength 
)

Get raw spectrum with meta-data. Only OBP enabled devices supported this command. The number of returned spectra depends on the following condition: 1) Device supports data buffering: A) If buffering is enabled then the number of spectra returned depends on how many spectra are in the buffer. It can be 0. B) If buffering is disabled then command will block until the requested number of spectra is received. 2) Device don't support data buffering: A) Only 1 spectra will be returned per call.

See also
SpectrumWithMetadata.h
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the size of the buffer is less than 1 or greater than 15; ERROR_NO_DEVICE if the device does not exist.
bufferthe buffer that will receive the formatted spectrum.
bufferLengththe actual size of the buffer.
Returns
the actual number of spectra copied into buffer.

◆ getScansToAverage()

unsigned int oceandirect::api::OceanDirectAPI::getScansToAverage ( long  deviceID,
int *  errorCode 
)

Get the number of spectra to be averaged per returned spectrum. When this value has been set greater than 1 the specified number of spectra are averaged and the resulting average is returned by getFormattedSpectrum (or getRawSpectrumWithMetadata).

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the number of spectra to be averaged per returned spectrum.

◆ getSerialNumber()

int oceandirect::api::OceanDirectAPI::getSerialNumber ( long  deviceID,
int *  errorCode,
char *  buffer,
int  bufferLength 
)

Get the serial number of the device.

See also
getSerialNumberMaximumLength
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the serial number feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
bufferthe buffer to receive the returned serial number.
bufferLengththe size of the supplied buffer.
Returns
the actual number of characters in the returned serial number.

◆ getSerialNumberMaximumLength()

unsigned char oceandirect::api::OceanDirectAPI::getSerialNumberMaximumLength ( long  deviceID,
int *  errorCode 
)

Return maximum length of the device serial number.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the serial number feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum length of the serial number.

◆ getStoredDarkSpectrum()

int oceandirect::api::OceanDirectAPI::getStoredDarkSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength 
)

Retrieve a previously stored dark spectrum for use in subsequent corrections i.e. dark correction and nonlinearity correction.

See also
setStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be retrieved.
darkSpectrumLengththe actual size of the dark buffer.
Returns
the size of the stored dark spectrum on success, zero otherwise.

◆ getTime()

long long int oceandirect::api::OceanDirectAPI::getTime ( long  deviceID,
int *  errorCode 
)

Return the system time of the device. The time is returned as an integer representing the number of microseconds since January 1 1970 based on the current device system clock.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.

◆ getTriggerMode()

int oceandirect::api::OceanDirectAPI::getTriggerMode ( long  deviceID,
int *  errorCode 
)

Get the spectrometer trigger mode. Please see your spectrometer documentation for valid values of the trigger mode.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the mode supplied is not valid; ERROR_NO_DEVICE if the device does not exist ERROR_COMMAND_NOT_SUPPORTED device don't support this command.
Returns
the current trigger mode being used by the device.

◆ getWavelengthCoefficients()

int oceandirect::api::OceanDirectAPI::getWavelengthCoefficients ( long  deviceID,
int *  errorCode,
double *  coeff,
int  length 
)

Get the coefficients of the polynomial used to calculate the wavelengths.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the wavelengths feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
coeffan array to receive the coefficient values.
lengththe actual length of the supplied coefficients array.
Returns
the actual number of coefficients copied into the coefficients array.

◆ getWavelengths()

int oceandirect::api::OceanDirectAPI::getWavelengths ( long  deviceID,
int *  errorCode,
double *  wavelengths,
int  length 
)

Get the wavelengths for each pixel of the specified device.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the wavelengths feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
wavelengthsan array to receive the wavelength values.
lengththe actual length of the supplied wavelengths array.
Returns
the actual number of wavelengths copied into the wavelengths array.

◆ isFeatureEnabled()

bool oceandirect::api::OceanDirectAPI::isFeatureEnabled ( long  deviceId,
int *  errorCode,
FeatureId  featureId 
)

Check if a specified feature is enabled for a device, return true if yes, false if not

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.
featureIdthe feature ID of interest (declared elsewhere in OceanDirectAPI.h).
Returns
true if the specified feature is enabled, false otherwise.

◆ nonLinearityCorrectionUsage()

bool oceandirect::api::OceanDirectAPI::nonLinearityCorrectionUsage ( long  deviceID,
int *  errorCode 
)
Deprecated:
Determine if nonlinearity correction is on or off on raw spectrum
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.
Returns
true if nonlinearity correction is turned on, false otherwise.

◆ nonlinearityCorrectSpectrum() [1/2]

int oceandirect::api::OceanDirectAPI::nonlinearityCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)

Nonlinearity correct a previously acquired illuminated spectrum after dark correction using a previously acquired dark spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success;
darkSpectrumthe buffer that contains the dark spectrum to be used prior to the nonlinearity correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ nonlinearityCorrectSpectrum() [2/2]

int oceandirect::api::OceanDirectAPI::nonlinearityCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)

Nonlinearity correct a previously acquired illuminated spectrum using a stored dark spectrum. This function performs a dark correction using a previously stored dark spectrum prior to performing the nonlinearity correction.

See also
setStoredDarkSpectrum
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ openDevice()

void oceandirect::api::OceanDirectAPI::openDevice ( long  deviceID,
int *  errorCode 
)

This will attempt to open the bus connection to the device with the given ID. After the device is closed the id becomes invalid. You need to call either probeDevices()/addNetworkDevice()/detectNetworkDevices() and getDeviceIDs() in order to have a valid id before reopening the device again. For a network connected device this function may return an error code if the device is not yet ready to accept incoming connection or the device is unreachable. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist;

◆ probeDevices()

int oceandirect::api::OceanDirectAPI::probeDevices ( )

Use the probeDevices() method to force the driver to look for any device that can be found automatically. If this is not called then such devices will not be available for use. This should be used when attempting to find USB devices. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Returns
the number of detected USB devices.

◆ setBoxcarWidth()

void oceandirect::api::OceanDirectAPI::setBoxcarWidth ( long  deviceID,
int *  errorCode,
unsigned short int  boxcarWidth 
)

Set the width of the boxcar smoothing to be applied to the returned spectrum. When this value is set greater than 0, boxcar smoothing (a moving average) is applied to the spectrum returned by getFormattedSpectrum (or getRawSpectrumWithMetadata). The width specified is the number of pixels either side of the central pixel of the average i.e. if the result of this function is n, the "full width" of the smoothing is 2*n+1.

Setting this value to 0 turns off the boxcar smoothing.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
boxcarWidththe width of the smoothing to be applied, or zero if smoothing is to be turned off.

◆ setDelayMicroseconds()

void oceandirect::api::OceanDirectAPI::setDelayMicroseconds ( long  deviceID,
int *  errorCode,
unsigned long  delayMicroseconds 
)

Set the acquisition delay to the specified number of microseconds.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the period supplied is not valid; ERROR_NO_DEVICE if the device does not exist
delayMicrosecondsthe acquisition delay period in microseconds.

◆ setIntegrationTimeMicros()

void oceandirect::api::OceanDirectAPI::setIntegrationTimeMicros ( long  deviceID,
int *  errorCode,
unsigned long  integrationTimeMicros 
)

Set integration time in microseconds.

Note
some devices that make use of onboard functionality to perform averaging have a different, larger, minimum integration time for acquisition when averaging is enabled. Refer to the documentation for your spectrometer to see if this is the case. The minimum integration time when averaging is enabled can be determined using getMinimumAveragingIntegrationTimeMicros.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INPUT_OUT_OF_BOUNDS if an invalid integration time is supplied; ERROR_INTEGRATION_TIME_BELOW_AVERAGING_MIN if averaging is enabled and the specified integration time is below the minimum required for averaging (see getMinimumAveragingIntegrationTimeMicros); ERROR_NO_DEVICE if the device does not exist.
integrationTimeMicrosthe desired integration time in microseconds.

◆ setScansToAverage()

void oceandirect::api::OceanDirectAPI::setScansToAverage ( long  deviceID,
int *  errorCode,
unsigned int  scansToAverage 
)

Set the number of spectra to be averaged per returned spectrum. When this value is set greater than 1 the specified number of spectra are averaged and the resulting average is returned by getFormattedSpectrum (or getRawSpectrumWithMetadata). NOTE: Some devices have a minimum integration time for averaging that is different to the minimum integration time for unaveraged acquisition (see your spectrometer documentation to determine if this is a requirement).

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INTEGRATION_TIME_BELOW_AVERAGING_MIN if the current integration time is below the minimum required for averaging it will not be possible to enable averaging (see getMinimumAveragingIntegrationTimeMicros); ERROR_NO_DEVICE if the device does not exist.
scansToAveragethe number of scans to be averaged

◆ setStoredDarkSpectrum()

void oceandirect::api::OceanDirectAPI::setStoredDarkSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength 
)

Store a dark spectrum for use in subsequent corrections i.e. dark correction and nonlinearity correction.

See also
getStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be stored.
darkSpectrumLengththe actual size of the dark spectrum buffer.

◆ setTime()

void oceandirect::api::OceanDirectAPI::setTime ( long  deviceID,
int *  errorCode,
long long int  timeInMicrosecond 
)

Sets the system time of the device. The time must be sepcified as the integer number of microseconds since 1 January 1970.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
timeInMicrosecondthe time to set the device system clock as the number of microseconds since 1 January 1970.

◆ setTriggerMode()

void oceandirect::api::OceanDirectAPI::setTriggerMode ( long  deviceID,
int *  errorCode,
int  mode 
)

Set the spectrometer trigger mode. Please see your spectrometer documentation for valid values of the trigger mode.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the mode supplied is not valid; ERROR_NO_DEVICE if the device does not exist.
modethe trigger mode to apply.

◆ shutdown()

static void oceandirect::api::OceanDirectAPI::shutdown ( )
static

No public destructor. Call this to force memory cleanup.


The documentation for this class was generated from the following file: