Main Content

imaqregister

Register third-party custom adaptor

Description

adaptors = imaqregister returns a list of registered third-party adaptors with their full paths. If there are no registered adaptors, imaqregister returns an empty cell array.

Note

The imaqhwinfo and videoinput functions use the adaptor base name, not the full path. For example, if the adaptor full path is "c:\adaptor.dll" (Windows®), "/local/adaptors/adaptor.so" (Linux®), or "/local/adaptors/adaptor.dylib" (macOS), the adaptor base name is "adaptor".

example

adaptors = imaqregister(adaptorpath) registers the specified third-party adaptor library and returns a list of all registered adaptors.

Registering an adaptor informs Image Acquisition Toolbox™ of the location of a third-party adaptor library. If you query the system for available image acquisition hardware by using imaqhwinfo, the toolbox makes available any previously registered adaptor libraries. The imaqregister function saves the name of the registered adaptor in the MATLAB® preferences directory so that the location persists across MATLAB sessions. Because imaqhwinfo caches the list of available adaptors, you might need to call imaqreset after calling imaqregister to make the newly registered adaptor available.

Note

The adaptor shared library (a DLL on Windows) is not the same as the driver shared library supplied by a hardware vendor (also a DLL on Windows). The adaptor shared library is specific to Image Acquisition Toolbox and is specified as such by the hardware vendor.

adaptors = imaqregister(adaptorpath,action) adds or removes the third-party adaptor from the list of available adaptors, as specified by action.

Examples

collapse all

Register a third-party adaptor in Image Acquisition Toolbox on a Windows system and preview its data. This example uses the demo adaptor included with Image Acquisition Toolbox, but you can follow these steps to register any custom third-party adaptor. To view the demo adaptor source files, navigate to the directory on your system. The exact file path might differ on your computer.

cd('C:\Program Files\MATLAB\R2019b\toolbox\imaq\imaqadaptors\kit\demo\')

Use imaqregister to inform Image Acquisition Toolbox of your third-party adaptor. For this example, consider a prebuilt version of the demo adaptor for Windows in the \toolbox\imaq\imaqadaptors\kit\demo\win64 folder.

imaqregister('C:\Program Files\MATLAB\R2019b\toolbox\imaq\imaqadaptors\kit\demo\win64\mwdemoimaq.dll')
ans = 1×1 cell array
    {'C:\Program Files\MATLAB\R2019b\toolbox\imaq\imaqadaptors\kit\demo\win64\mwdemoimaq.dll'}

The toolbox caches adaptor information, so you must reload the adaptor libraries registered with the toolbox for your third-party adaptor to appear.

imaqreset

View a list of installed adaptors in the InstalledAdaptors field. The newly registered third-party adaptor appears as mwdemoimaq.

imaqhwinfo
ans = struct with fields:
    InstalledAdaptors: {'demo'  'gentl'  'gige'  'kinect'  'matrox'  'mwdemoimaq'  'spinnaker'  'winvideo'}
        MATLABVersion: '9.7 (R2019b)'
          ToolboxName: 'Image Acquisition Toolbox'
       ToolboxVersion: '6.1 (R2019b)'

Create a video input object with this adaptor.

vid = videoinput('mwdemoimaq')
Summary of Video Input Object Using 'Color Device'.

   Acquisition Source(s):  input1 is available.

  Acquisition Parameters:  'input1' is the current selected source.
                           10 frames per trigger using the selected source.
                           'RGB_NTSC' video data to be logged upon START.
                           Grabbing first of every 1 frame(s).
                           Log data to 'memory' on trigger.

      Trigger Parameters:  1 'immediate' trigger(s) on START.

                  Status:  Waiting for START.
                           0 frames acquired since starting.
                           0 frames available for GETDATA.

Get a preview of the data returned by the adaptor.

preview(vid)

After you finish working with the preview, close the window.

closepreview(vid)

Input Arguments

collapse all

Adaptor path, specified as a character vector or string array. You must specify the full absolute path of the adaptor library file.

Example: imaqregister('c:\temp\thirdpartyadaptor.dll') registers the adaptor thirdpartyadaptor.

Data Types: char | string

Adaptor registration, specified as 'register' or 'unregister'. Using 'register' adds the third-party adaptor to the list of available adaptors. Using 'unregister' removes the third-party adaptor from the list.

Example: imaqregister('c:\temp\thirdpartyadaptor.dll','unregister') removes the adaptor thirdpartyadaptor.

Data Types: char | string

Tips

  • Follow these suggestions when you deploy a custom adaptor to a standalone application using MATLAB Compiler™.

    • Call imaqregister in the MATLAB code that you are deploying. This ensures that the deployed application registers the custom adaptor library for the user running the application. For more information, see Creating Custom Adaptors.

    • Package the custom adaptor library with the standalone application. To do this, add the adaptor DLL file in the Files installed for your end user section of the Application Compiler app. For more information about creating a standalone application, see Create Standalone Application from MATLAB Function (MATLAB Compiler).

    • The first time you run a deployed application that calls imaqregister, you might need to execute the application in Run as administrator mode.

Version History

Introduced before R2006a