ApBase API Development Guide
- 1 Introduction
- 2 Quick Start
- 3 Functions for Enumerating and Opening Devices
- 4 Functions for the Debug Log
- 5 Functions for Executing Scripts
- 6 Functions for Reading Sensor or ISP Registers
- 7 Functions for Writing Sensor or ISP Registers
- 8 Functions for Enumerating Sensor, ISP or Demo Kit Registers
- 9 Functions for Enumerating Sensor, ISP or Demo Kit Bitfields
- 10 Functions for Accessing Any Device Register
- 11 Functions for Getting and Processing Images
- 12 Setting Callback Functions
- 13 Library Version and Utilities
- 14 Frequently Asked Questions (FAQ)
Current as of Release 5.0.37
Introduction
The ApBase API provides an easy to use interface for controlling Aptina demo kit cameras.
ApBase performs these primary functions:
Enumerate all of the demo kit cameras that are connected to the host PC.
Run initialization scripts start the camera or change modes.
Provide read/write access to sensor/SOC/ISP registers. Further, ApBase understands what register settings on the sensor do, keeps track of all relevant sensor modes, and automatically updates the demo kit hardware when the sensor mode changes. For example, if a register write enables MIPI output from the sensor, ApBase will automatically enable the MIPI receiver on the demo kit hardware.
Receive images from the camera device.
Convert the image received from the demo kit into RGB for saving to a file or displaying on the screen.
Additional Information can be found in the following documents
State Variables; as used in INI files with "STATE=", see "ap_GetState" and "ap_SetState" for usage.
Modes; there are a few modes setings from INI files, see "ap_GetMode" and "ap_SetMode" for usage.
"apbase.h"; many other calls are available and found by searching for "ap_".
ApBase API is available in 64-bit only.
Quick Start
To use ApBase in C or C++, include the apbase.h header file, and link to apbase.lib.
When running the application, be sure that the following folders supplied with the DevWare installer are present;
apps_data, board_data, and sensor_data
Sample programs can be found here:
C:\Aptina Imaging\samples\SimpleQt
C:\Aptina Imaging\samples\SimpleCapture
Here is a minimal procedure to open a demo kit camera, initialize the Aptina device, grab an image and convert it to RGB.
#include "apbase.h"
AP_HANDLE hApBase = ap_Create(0);
if (hApBase == NULL)
return;
ap_LoadIniPreset(hApBase, NULL, NULL); // initialize the sensor with the default from "Demo Initialization" preset
// Read all sensor registers and configure the Demo3 and software according to the sensor settings.
ap_CheckSensorState(apbase, 0);
size_t bufSize = ap_GrabFrame(hApBase, NULL, 0);
unsigned char *pBuffer = new unsigned char [bufSize];
ap_GrabFrame(hApBase, pBuffer, bufSize);
unsigned char *pRGB = NULL;
ap_u32 rgbWidth = 0, rgbHeight = 0, rgbBitDepth = 0;
if (ap_GetLastError() == MI_CAMERA_SUCCESS)
pRGB = ap_ColorPipe(hApBase, pBuffer, bufSize, &rgbWidth, &rgbHeight, &rgbBitDepth);
delete [] pBuffer;
ap_Destroy(hApBase);
ap_Finalize();
Note: The call to ap_LoadIniPreset() with NULL 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: when using a Demo3, it is recommended to perform a single call to ap_GrabFrame() after the call to ap_LoadIniPreset() to ensure that the Demo3 FIFO doesn't have a partial frame.
Please check out our YouTube video on ApBase for a quick overview.
Functions for Enumerating and Opening Devices
If using a specific verison of Python, set the path first using ap_SetPythonEnvPath().
To access the camera, first create a device handle using a Create call, or a Probe call followed by a Create call.
void ap_SetPythonEnvPath(const char *szPythonDir)
Parameters
Python install path; for example, "\\Users\\acecoder\\AppData\\Local\\Programs\\Python\\Python39".
Remarks
Must be called before device creation - recommended to make it the first ApBase call.
ap_s32 ap_DeviceProbe(const char *szSensorDataDirOrFile)
Parameters
A pointer to a file name or directory name. Can be NULL.
Return Value
Error code.
Remarks
Search the system for Aptina demo kit devices or other compatible camera devices, identify the type of sensor or ISP, and build a set of internal data structures for each device. Use ap_Create() to create the handle used by the other API functions to access the device.
If the parameter is NULL, 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.
ApBase will keep track of the modes and state of all of the devices. When the application is done using the ApBase API, call ap_Finalize() to close all drivers and free all memory associated with the devices.
ap_s32 ap_DeviceProbeDll(const char *szSensorDataDirOrFile, const char *szTransportDll)
Parameters
szSensorDataDirOrFile: a pointer to a file name or directory name. Can be NULL.
szTransportDll: a pointer to the location of the replacement Transport DLL. Can be NULL.
Return Value
Error code.
Remarks
Like ap_DeviceProbe(), except an alternative Transport DLL can be defined. See ap_DeviceProbe() for additional information.
void ap_CancelProbe()
Cancel a device probe in progress in another thread.
int ap_NumCameras()
Return Value
Number of cameras.
Remarks
Return the number of cameras discovered by the device probe function.
void ap_Finalize()
Close all drivers and free all memory associated with the devices. Any existing AP_HANDLEs become invalid, so destroy all handles first.
ap_s32 ap_GetLastError()
Comments
Sorry for the delay in our reply.
Yes. For Windows, it is already provided as "apbase_64.dll"; see file "Windows_64-bit_ReadMe.txt" for details.
We also have Linux (Unbuntu) and MacOS installers. https://aptina.atlassian.net/wiki/display/DEVS/Software+Downloads?src=contextnavpagetreemode
Thanks for the hint. I used Matlab to run apBase Api on both Win 7 and Matlab on 32 bit System. This was working quite fine.
Now I tried to use apBase on Win 7 / Matlab 64 bit but didn't succeed until now..Matlab error code is:
actxserver('apbaseCom.ApBase')
Error using feval Server Creation Failed: Klasse nicht registriert
It seems, that the API in 64 bit Windows is not registered correct. Do you have any hints how to overcome this Problem?
Yes.
For Windows, see "Windows_64-bit_ReadMe.txt".
We also have 64-bit installers for Linux (Ubuntu) and MacOS;
"https://aptina.atlassian.net/wiki/display/DEVS/Software+Downloads?src=contextnavpagetreemode"
Is there any more information on timing? Is grabFrame waiting for a frame to arrive? Is there software trigger that allows to synchronize acquisition with the VSync of an OpenGL context?
I'm also interested in synchronizing acquisition. Could any of the ap_SetCallback functions be used for this?
Also, is midlib2 compatible with USB3/Demo3? apbase works for me (on Linux), but if I use midlib directly, mi_grabFrame fails with MI_GRAB_FRAME_ERROR and imageBytesReturned is always 16384. Does ap_Create do any other setup besides mi_OpenCameras and mi_startTransport ?
Midlib2 is compatible with USB3/Demo3. ApBase is built on midlib2, and uses midlib2 for all I/O.
Yes, ApBase does other setup. Most importantly mi_updateFrameSize, and as many calls to mi_setMode as are necessary (notably to set up MIPI or HiSPi modes, but other settings as well), depending on the sensor register settings. A major motivation for the move to ApBase was because so much more initialization is necessary with modern devices. We had all of that code in DevWare, so we embodied it in ApBase to make it available to other applications.
Thank you for the information. So mi_LoadINIPreset does not perform the necessary calls to mi_updateFrameSize and mi_setMode and using apbase is effectively mandatory. It's only that midlib's minimal dependencies would make life easier.
As for synchronization (with a change in lighting in my case), my understanding was that I would initialize with streaming disabled via an ini file and then toggle streaming to capture an image at a particular time using
ap_SetSensorRegister(apbase, "RESET_REGISTER", "STREAM", 1, NULL);
ap_SetSensorRegister(apbase, "RESET_REGISTER", "STREAM", 0, NULL);
However, regardless of whether I initialize with streaming enabled or insert delays between these ap_SetSensorRegister calls, I always end up with the same MI_GRAB_FRAME_ERROR and frameLength 16384 that I received when trying to use midlib directly. So it appears I cannot take timed snapshots without understanding some of the mi_setMode magic that apbase does. Or am I missing something?
Apbase isn't strictly mandatory, but you would need to make the additional midlib calls. If your setup is unchanging and you know what it is, that isn't much code.
We do recommend switching to all ApBase calls - they are designed to perform all necessary settings.
After calling ap_LoadIniPreset, you should be streaming. If not, then that is the first issue to solve. If you are streaming after ap_LoadIniPreset then those RESET_REGISTER calls should work as expected. Since you want to guarantee a fresh frame after a time period with streaming off, you should clear out the Demo board buffers with
ap_SetMode(apbase, "MI_RESET_IMAGE_FIFO", 0);
before you turn streaming back on again.
I would greatly appreciate any documentation of what midlib calls need to be made to setup the device. Using ap_/mi_ get/set mode functions I have used midlib2 to set all of the modes to be identical to how they're set after ap_LoadIniPreset, but mi_updateFrameSize does not appear to work. Also, while apbase does not enable MI_SPI_REG_ACCESS mode, I cannot read or write registers with midlib2 unless I enable it.
Using apbase, I can now toggle the stream bit successfully. Originally, I toggled it on and off before calling ap_GrabFrame, since the sensor datasheet implies that turning it off does not take effect until the end of the current frame. But ap_GrabFrame fails if it is off. Unfortunately, turning streaming off immediately after ap_GrabFrame halves the frame rate, presumably because it starts another frame each time. What we are trying to achieve is a short, say 1ms, gap between frames, and control or at least knowledge of when a frame starts.
Is there any other support channel for Devwarex?
Is the apbase API available for 64 bit architecture?