...
The ApBase COM object makes key functions of the ApBase API available via the COM (Component Object Model) mechanism.
Quick Start
To use ApBase COM, create an object of type apbaseCom.ApBase. The details will depend on the tool or language you are using. The following example is in Matlab.
Here is a minimal procedure to open a demo kit camera, initialize the Aptina device, grab an image and convert it to RGB.
...
apbaseCom.ApBase Methods and Properties
First create an object of type abpaseCOM.ApBase. Then use this object to enumerate devices and create a camera object.
The ApBase object is free-threaded.
LONG DeviceProbe(BSTR sSensorDataDirOrFile)
Parameters
A file name or directory name, or an empty string.
...
Error code.
...
Search the system for Aptina demo kit devices or other ApBase compatible camera devices, identify the type of sensor or ISP, and build a set of internal data structures for each device. Use Create() to create a camera object.
...
void CancelProbe()
Cancel a device probe in progress in another thread.
LONG NumCameras
Property Value
Number of cameras.
...
Return the number of cameras discovered by the device probe function.
void Finalize()
Close all drivers and free all memory associated with the devices. Any existing camera objects become invalid. Called automatically when the object is released.
LONG LastError
Property Value
Error code.
...
The error code from the last function call made in the current thread.
LONG LastSideEffects
Property Value
Side effects flags.
Remarks
The side effects flags from the last register write made in the current thread.
IApCamera Create(LONG nDeviceIndex)
Parameters
A device index, 0…NumCameras – 1.
Return Value
An apbaseCOM.ApCamera object.
Remarks
Create a camera object for one of the devices discovered by the device probe. If the device probe has not been done yet, this function will call DeviceProbe() with the default parameters.
Creating and destroying these objects does not affect the device or the device state information kept within ApBase.
After creating a camera device, call LoadIniPreset() or CheckSensorState() to make sure the state of the object is synchronized with the state of the device.
IApCamera CreateFromImageFile(BSTR sFilename)
Parameters
An image file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create a camera object from an image file. This is a way to make use of the image file reading feature of ApBase. Calling GrabFrame() on this object will retrieve the image. The ColorPipe() call can convert it to RGB if it is not RGB already, for example a Bayer image or YCbCr image.
Note:Although it's possible to pass an image file name to DeviceProbe() and call Create(0) to get a camera device object, that method then precludes the possibility of probing for physical camera devices. This function is the preferred way to make a camera object from an image file.
IApCamera CreateVirtual(BSTR sFilename)
Parameters
A sensor data file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create an in-memory camera object from a sensor data file. This is a way to make use of the sensor data file parsing feature of ApBase. No I/O can be done on the resulting object, but it is possible to numerate the registers and get other property values defined in the sensor data file.
BSTR Home
Property Value
Path to the Aptina Imaging installation folder.
BSTR SensorData
Property Value
Path to the sensor_data installation folder where sensor data files are stored.
BSTR Version
Property Value
The software version number as a string. Example '5.0.24.46000'.
BSTR BuildName
Property Value
Software build name string. Example '5.0.24_Release'.
void OpenIoLog(ULONG nLogFlags, BSTR sFilename)
Parameters
nLogFlags – A combination of AP_LOG_x flags.
sFilename – Name of a file for the log data. A new file is created each time this function is called. Digits 0, 1, etc. will be appended to the file name.
Remarks
Starts a new log file. The file extension is usually .txt. Digits are appended to the filename so the previous log is not overwritten when the program is run again. Use ap_GetIoLogFilename() to get the actual log filename if needed.
void CloseIoLog()
Remarks
Close the current I/O log file.
BSTR IoLogFilename()
Property Value
The current I/O log file name.
Remarks
This function can be called after CloseIoLog(), and will return the most recent log filename.
void IoLogMsg(BSTR sText)
Parameters
sText – A text string to add to the log.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
void IoLogDebugMsg(BSTR sText, BSTR sSource, BSTR sFunc, ULONG nLine)
Parameters
sText – The message for the log.
sSource – Name of the current source file. Can be empty.
sFunc – Name of the calling function.
nLine – Line number of the source file.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG_DEBUG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
The sSource, sFunc, and nLine parameters are optional; if included they will be appended to the message. They are included to make it easy to find the location in your source code where a debug message originated from. Many compilers have macros like _FILE, __FUNCTION, __LINE_ that can be used here.
apbaseCom.ApCamera Properties
Properties of the apbaseCOM.ApCamera interface.
BSTR Name
Property Value
Name of device or sensor.
Remarks
Can be different from the part number. Read only.
BSTR PartNumber
Property Value
Part number.
LONG Version
Property Value
Revision number. Read only.
BSTR VersionName
Property Value
Version string.
Remarks
Usually like REV1, REV2, etc., but can be more descriptive in some cases. Read only.
BSTR FileName
Property Value
The name of the file the device parameters are based on.
Remarks
A .xsdat file for a physical camera, or an image or video file name. Read only.
LONG Width
Property Value
Image width in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
LONG Height
Property Value
Image height in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
BSTR ImageType
Property Value
The image type as a string.
Remarks
...
Note: ApBaseCOM does not use Matlab itself, but if you are using DevWare plug-ins that use Matlab, you must install the MatLab Runtime library via this link.
http://www.onsemi.com/pub/Collateral/MCRINSTALLER.ZIP
ApBaseCom.DLL Registration
Although the software installer registersapbaseCom.dll, it is possible that the registration process fails without warning.
If you experience errors regarding server creation, please perform the following;
- Search for “Command Prompt” from Start menu, right click on it and select “Run as administrator”.
- Navigate to the installation folder, usually “C:\Aptina Imaging\bin”.
- Enter; %SystemRoot%\system32\regsvr32 apbasecom.dll
- A “RegSvr32” dialog will appear with “DllRegisterServer in apbasecom.dll succeeded”.
Quick Start
To use ApBase COM, create an object of type apbaseCom.ApBase. The details will depend on the tool or language you are using. The following example is in Matlab.
Here is a minimal procedure to open a demo kit camera, initialize the ON Semiconductor device, grab an image and convert it to RGB.
% open ApBase and Camera, and initialize via "Demo Initialization" preset
apbase = actxserver('apbaseCom.ApBase');
camera = apbase.Create(0);
camera.LoadIniPreset('', '');
% Throw-away the first frame after initialization
raw = camera.GrabFrame;
% grab a frame, convert to RGB
raw = camera.GrabFrame;
rgb = camera.ColorPipe(raw);
Note: The call to LoadIniPreset() with blank parameters is only applicable in situations where the default initialization is sufficient. For demo kits with multiple possible configurations, such as ISP + sensor combinations or different connection options, you will need to specify the particular initialization preset for the configuration.
Note: The rgb image is one long line; this is for performance reasons.
In Matlab you will need to reshape it for display
apbaseCom.ApBase Methods and Properties
First create an object of type abpaseCOM.ApBase. Then use this object to enumerate devices and create a camera object.
The ApBase object is free-threaded.
LONG DeviceProbe(BSTR sSensorDataDirOrFile)
Parameters
A file name or directory name, or an empty string.
Return Value
Error code.
Remarks
Search the system for ON Semiconductor demo kit devices or other ApBase compatible camera devices, identify the type of sensor or ISP, and build a set of internal data structures for each device. Use Create() to create a camera object.
If the parameter is an empty string, the default installation directory is searched for a sensor data file matching each device. Otherwise the parameter can be a specific sensor data file (.xsdat file) to be used with the device, or a directory to be searched for compatible sensor data files.
void CancelProbe()
Cancel a device probe in progress in another thread.
LONG NumCameras
Property Value
Number of cameras.
Remarks
Return the number of cameras discovered by the device probe function.
void Finalize()
Close all drivers and free all memory associated with the devices. Any existing camera objects become invalid. Called automatically when the object is released.
LONG LastError
Property Value
Error code.
Remarks
The error code from the last function call made in the current thread.
LONG LastSideEffects
Property Value
Side effects flags.
Remarks
The side effects flags from the last register write made in the current thread.
IApCamera Create(LONG nDeviceIndex)
Parameters
A device index, 0…NumCameras – 1.
Return Value
An apbaseCOM.ApCamera object.
Remarks
Create a camera object for one of the devices discovered by the device probe. If the device probe has not been done yet, this function will call DeviceProbe() with the default parameters.
Creating and destroying these objects does not affect the device or the device state information kept within ApBase.
After creating a camera device, call LoadIniPreset() or CheckSensorState() to make sure the state of the object is synchronized with the state of the device.
IApCamera CreateFromImageFile(BSTR sFilename)
Parameters
An image file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create a camera object from an image file. This is a way to make use of the image file reading feature of ApBase. Calling GrabFrame() on this object will retrieve the image. The ColorPipe() call can convert it to RGB if it is not RGB already, for example a Bayer image or YCbCr image.
Note:Although it's possible to pass an image file name to DeviceProbe() and call Create(0) to get a camera device object, that method then precludes the possibility of probing for physical camera devices. This function is the preferred way to make a camera object from an image file.
IApCamera CreateVirtual(BSTR sFilename)
Parameters
A sensor data file name. Cannot be NULL.
Return Value
ApCamera object.
Remarks
Create an in-memory camera object from a sensor data file. This is a way to make use of the sensor data file parsing feature of ApBase. No I/O can be done on the resulting object, but it is possible to numerate the registers and get other property values defined in the sensor data file.
BSTR Home
Property Value
Path to the ON Semiconductor Imaging installation folder.
BSTR SensorData
Property Value
Path to the sensor_data installation folder where sensor data files are stored.
BSTR Version
Property Value
The software version number as a string. Example '5.0.24.46000'.
BSTR BuildName
Property Value
Software build name string. Example '5.0.24_Release'.
void OpenIoLog(ULONG nLogFlags, BSTR sFilename)
Parameters
nLogFlags – A combination of AP_LOG_x flags.
sFilename – Name of a file for the log data. A new file is created each time this function is called. Digits 0, 1, etc. will be appended to the file name.
Remarks
Starts a new log file. The file extension is usually .txt. Digits are appended to the filename so the previous log is not overwritten when the program is run again. Use ap_GetIoLogFilename() to get the actual log filename if needed.
ULONG IoLogFlags
Property Value
Flags controlling which logging output is enabled.
1: Errors
2: Minor errors
4: Messages from IoLogMsg() calls
8: Register read/write traffic
16: I/O transport (USB) traffic
32: Messages from IoLogDebugMsg() calls and internal debug messages
void CloseIoLog()
Remarks
Close the current I/O log file.
BSTR IoLogFilename()
Property Value
The current I/O log file name.
Remarks
This function can be called after CloseIoLog(), and will return the most recent log filename.
void IoLogMsg(BSTR sText)
Parameters
sText – A text string to add to the log.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
void IoLogDebugMsg(BSTR sText, BSTR sSource, BSTR sFunc, ULONG nLine)
Parameters
sText – The message for the log.
sSource – Name of the current source file. Can be empty.
sFunc – Name of the calling function.
nLine – Line number of the source file.
Remarks
The text will be added to the log if there is a log file currently open and AP_LOG_DEBUG was one of the flags passed to OpenIoLog(). A newline at the end of the string is not needed. The text will be preceded by a timestamp in the log file.
The sSource, sFunc, and nLine parameters are optional; if included they will be appended to the message. They are included to make it easy to find the location in your source code where a debug message originated from. Many compilers have macros like _FILE, __FUNCTION, __LINE_ that can be used here.
apbaseCom.ApCamera Properties
Properties of the apbaseCOM.ApCamera interface.
BSTR Name
Property Value
Name of device or sensor.
Remarks
Can be different from the part number. Read only.
BSTR PartNumber
Property Value
Part number.
LONG Version
Property Value
Revision number. Read only.
BSTR VersionName
Property Value
Version string.
Remarks
Usually like REV1, REV2, etc., but can be more descriptive in some cases. Read only.
BSTR FileName
Property Value
The name of the file the device parameters are based on.
Remarks
A .xsdat file for a physical camera, or an image or video file name. Read only.
LONG Width
Property Value
Image width in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
LONG Height
Property Value
Image height in pixels.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
BSTR ImageType
Property Value
The image type as a string.
Remarks
This property can be set, but setting it does not affect the state of a physical camera. The width, height, and image type can be set together in one call with SetImageFormat().
The possible image types are "BAYER-6", "BAYER-8", "BAYER-10", "BAYER-8+2", "BAYER-10IHDR", "BAYER-12", "BAYER-12HDR", "BAYER-8+4", "BAYER-14", "BAYER-14HDR", "BAYER-16", "BAYER-20", "BAYER-16+4", "BAYER-STEREO", "YCBCR", "YCBCR-16", "YCBCR-10", "YCBCR-20", "YUV-420", "M420", "RGB-565", "RGB-555", "RGB-444X", "RGB-X444", "RGB-332", "RGB-24", "RGB-32", "RGB-48", "BGRG", "JPEG", "JPEG-SPEEDTAGS", and "JPEG-ROT"and "JPEG-ROT".
BSTR GetFuseID(LONG nIndex)
Parameters
nIndex – Index of the device if there are more than one.
Remarks
Gets the FuseID of the device as ASCII hex digits. The nIndex parameter can be used if there are more than one device with a FuseID; for example in the case of an AP0200 with an AR0140 attached, nIndex = 0 will get the AP0200 FuseID, and nIndex = 1 will get the AR0140 FuseID. Use 0 in most cases.
Functions for Executing Scripts
...
Get the next image from the camera.
Use LastError for the error code.
Note: after initialization via "LoadIniPreset('', '')", do a call to GrabFrame() to throw-away the first frame due to possibility it will be a partial frame - first-waffle kind of thing.
Frames after that will be full frames.
VARIANT ColorPipe(VARIANT inImage, ULONG *outWidth, ULONG *outHeight, ULONG *outBitDepth)
...
Get the value of an integer-valued color pipe state variable. See the State STATE Variables for a list of color pipe variables.
...
Set the value of an integer-valued color pipe state variable. See the State STATE Variables for a list of color pipe variables.
...
Get the value of a string-valued color pipe state variable. See the State STATE Variables for a list of color pipe variables.
...
Set the value of a string-valued color pipe state variable. See the State STATE Variables for a list of color pipe variables.
...