My Issues

Drivers Manual

DSLR Camera - Basler - 32

Description

This driver with user-interface can be used to:

  1. Control a Basler Industrial camera.
  2. Automatically capture images to JPG files.
  3. Update the image file meta information (EXIF) with GPS time and co-ordinates.


These captured and geo-tagged images (JPEG format) can be viewed using a Navigation Display, the Processing Manager, or with Google Earth.

The driver was tested with the following camera: Basler acA2500-60uc camera. Other Basler cameras are expected to work but should be tested before purchase/deployment.

Typical application

A Basler camera is mounted on a vehicle, e.g. a car, and interfaced to QINSy, together with a GPS, a motion and a heading sensor. 

The Controller may for example generate a fix every 100 meters, triggering the Basler camera to capture an image. 
All images are automatically stored in a user-defined folder on the QINSy computer, updated with the exact location at time of capturing. 

The image filename may also contain user-defined name specifiers, like project name, line name, position co-ordinates, sequence number, etc., in order to make further processing and archiving easy.

 

Driver Information

Driver

DSLR Camera - Basler

Interface Type USB3

Driver class type

Freebase

UTC Driver (question)

No

Input / Output Input and Output

Executable

DrvBaslerCameraUI.exe

Related Systems
Related Pages

Issues

  • This driver is limited to a single camera per template database.
  • Basler cameras using the IIDC 1394, GigE Vision & Camera Link interfaces have NOT been tested but are expected to work. Customers are recommended to test before camera purchase and/or mobilization as no guarantees are given.
  • In case a customer uses this driver with a Basler camera which is different from the 'Basler acA2500-60uc' camera please inform QPS via JIRA so that we may update this documentation.
  • During the testing of this driver it was discovered that anti-virus software may influence the time it takes to grab an image. Please try disabling the anti-virus software in case grabbing an image takes too long.
  • This driver was tested with the following runtime version: 'pylon 5 Runtime 5.0.5.8999'.

New

  • This is the initial version of this driver description. It may be updated when new information becomes available.

Interfacing Notes

Basler cameras may be connected to the QINSy computer using one of the following interfaces:

  • USB3 Vision interface
  • IIDC 1394 interface
  • GigE Vision interface
  • Camera Link interface

It is recommended to use a Basler supplied cable to connect the camera. If possible connect the camera directly to the computer instead of via a USB hub or Ethernet switch. In case a USB hub is used it should be USB3.

It is important that the correct Windows drivers are installed for communication between your camera and the Windows operating system.
These drivers are normally supplied with your camera, or instructions on how to obtain them come with the camera's documentation. They may also be downloaded here from the Basler website.


You may use the following quick check in case a Basler camera with an USB3 Vision interface is used: 

If you can see the camera using the 'pylon USB Configurator', then you can start the Controller to go on-line and proceed using this QINSy driver without any (connection) problem. 
The 'pylon USB Configurator' is part of the Basler supplied software.



If you can not see the camera in the 'pylon USB Configurator', then there is no need to go online yet: you must first solve this problem.

QINSy Configuration

Database Setup

Add an AIS System to Database Setup and select the "DSLR Camera - Basler" driver from the list.

No other interfacing settings are required, but make sure that there is already a successful USB3 or other interface connection. See System Interfacing for more information about this.

Notice that this driver is handled internally as an AIS system, but no extra data is stored in the database during recording.

All on-line acquired images are stored as *.jpg files in a separate folder.

Online

Note

When the camera is (re-)connected while the Controller is already running, you may just start using it.

The driver should automatically find the camera.


The driver has user-interface and therefore will always be present in the Windows task-bar.

When going on-line for the first time, locate the driver and change the Node Setup and some default Options parameters:


The driver's dialog has an upper and a lower pane and four buttons in the middle.

The upper pane is reserved to show three different menus, a Node Setup, a Camera and an Options menu, which are accessible using the three menu buttons.

The lower pane is used for displaying all kinds of information, warnings and error messages. You may clear the entire message list using the [ Clear ] button.


Driver Layout Menu: Node Setup 

Select the button [ Node Setup ] to activate the Node Setup menu. 

This menu is normally only needed during setup time. When finished, you may check the options in the 'Options' menu, or go to the 'Camera' menu. 

Notice there is no 'Apply' or 'OK' button in order to activate modifications, so changes will have effect immediately. 

Node Setup

Node

Select the node location of the camera.
Notice that a node and computation must be selected in order to capture images.

Computation Select the computation for the node location of the camera.

Camera Orientation

Enter the camera orientation, in degrees (0°..360°), relative to the vehicle's heading.
This information will be stored as EXIF metadata.

Camera Tilt

Enter the camera tilt angle, in degrees (-90°..+90°).
-90° means camera looking straight down, 0° means horizontal and +90° means camera looking straight up.

Camera Latency

Enter the latency in milliseconds. This is the time between the capture command send and the actual time of capture.
See Tips and Tricks below for more information about this.

Copyright

Enter your own free text. This copyright information will be stored as EXIF metadata.

Node Result

The current position of the selected node.
Displayed are the UTC time, Easting/Northing in Grid or Lat/Lon on WGS84 and the Height on Vertical datum. This information will be stored as EXIF metadata.

The indicator cycles when valid positions are received. Notice that without a valid position no images will be captured.



Driver Layout Menu: Options 

Select the button [ Options ] to activate the Options menu 

Options

Image Destination

Define where the captured images should be stored automatically.
You may use the [ Browse... ] option to use another folder than the listed sub-folders from the current project.

Image Folder

Use the button to browse for another folder than a sub-folder from the current project.

Image Filename

The name of the captured images. Notice that the extension will automatically be jpg.
A suffix (counter) will be added automatically when the image already exists.
Usage:
Enter your own free text, plus you may use the following format specifiers:
#P=Project name, #S=Storage file, #L=Mainline, #F=Fix
%d=day, %m=month, %y=year, %j=Julian Date
%H=hours, %M=minutes, %S=seconds
Use #GRID or #GEO for position co-ordinates
Use #C for a unique incremented counter

Update EXIF (GPS, etc)

It is highly recommended to be enable this option.
Update the image with EXIF metadata, like GPS, copyright, etc..
This option is by default enabled.

Create Trajectory (QCT)

Enable to store a daily camera trajectory log file, in the project's Logfile folder.
QCT Format (comma separated):
"Time, Image Name, Easting, Northing, Height, Orientation, Roll, Pitch<CR><LF>"
This option is by default enabled.

Create Line Data (QGF)

Store position of each captured image as point objects to a Line data (*.QGF) file.
These point objects can be viewed using a Navigation Display, or with the Processing Manager.
This option is by default enabled.

This line data file is always located in the project's 'LineData' sub-folder and has the following name convention:
<driver's system name> <dd-mm-yyyy>.QGF, where driver's system name is the name of the system as entered in the Database template Setup.

This file may be selected in the Navigation Display (View Properties, Layers, Line Databases) in order to show the exact location of each captured image as point object.
Notice that this file is only updated to disk when the Capture Mode/When option is changed (e.g. to [On Hold]), or when a Manual Capture action is performed.
The radius of each point object reflects the SOG (speed over ground) in survey units/sec of the vehicle at time of capture.
A red colored point object indicates that the image was not captured for some reason.

Create Google Earth (KML)

Enabled to create a *.kml file with every captured image, in the same folder, with the same filename.
Kml files may be opened using the 'Google Earth' program.
This option is by default disabled.

Display Positions

The position results as displayed in Node Setup and Camera menu will be as Easting/Northing (Grid) or as Lat/Lon (Geo) on the WGS84 datum.
This option is by default set to Grid.

Show Tooltips

When hovering the mouse over the left column rows, you will get some more information. Disable if this becomes annoying.
This option is by default enabled.

Lock Settings

You may lock the user-interface settings, in order to prevent making changes by mistake.



Driver Layout Menu: Camera 

Select the button [ Camera ] to activate the Camera menu. 

This menu should be active during normal operations: 


Camera

Capture Mode

Select the capture mode for capturing images automatically:

  • Manually
    No images will be captured automatically, they will only be captured when action Manual Capture is selected.
  • On Time
    The camera is triggered to capture an image when a certain time period has elapsed.
    This time period depends on the selected Time interval.
  • On Fix
    The camera is triggered to capture an image when the Controller generates a fix event.
    Fix eventing parameters are defined in the Controller's Session Setup.
  • On Fix (Odd)
    The camera is triggered to capture an image when the Controller generates a fix event with an odd fix number.
    Fix eventing parameters are defined in the Controller's Session Setup.
  • On Fix (Even)
    The camera is triggered to capture an image when the Controller generates a fix event with an even fix number.
    Fix eventing parameters are defined in the Controller's Session Setup.

Time Interval

Enter the capture time interval in seconds, when capture mode is On Time.
For example, if you want to capture an image every half a minute , leave this value to 30 (default).

Fix Interval

Enter the capture fix interval, when capture mode is on fix.
Fix events are generated by the Controller.
If you want to capture an image every fix event, then set this value to 1 (default).

When

  • [On Hold]
    No image will be captured automatically.
    Notice that this setting is always selected when going on-line, in order to prevent capturing images immediately during start-up and initialization time.
  • Always
    Images will be captured when the time interval has elapsed (mode On Time), or when a fix event has been generated (mode On Fix).
  • Only When Recording
    Images will only be captured automatically when the Controller is recording.

Select Action

Notice that a selected action is only performed when using the Action button on the next row.

The following actions can be selected:

  • [None]
    The action button on the next row will not be visible.
  • Reset unique filename counter
    This action only has effect when using the #C format specifier in the image file name (see Options menu). It will set the counter back to 1, so the next captured image will have '001' in its filename.
  • Manual Capture
    When the camera is not busy you can always take a picture using this manual capture action.

Action

The action that will be performed depends on the Select Action setting on the previous row. See explanation above.

Settings File

Filename of the camera settings file which is automatically loaded during the startup phase of the driver. The selected camera settings file may be changed by using the button to select a different file.
The selected file must be of the file type 'Pylon Feature Stream' (*.pfs). These files may be created using the 'Save Features' option in the 'Camera' menu of the 'Pylon Viewer' program.

The 'Pylon Viewer' program is part of the software which may be downloaded from the Basler web site.

Image File

Filename of the last captured image. Use the button to view the image with your default viewer.

Information

UTC Time and file size of the last captured image.

Position

Position co-ordinates of the last captured image.
Easting/Northing in Grid or Lat/Lon on WGS84 and Height on Vertical datum.
This information is also stored as EXIF metadata.

Additional Information

Tips and Tricks

The following tips and tricks were written with all DSLR drivers in mind and some options therefore may not be applicable to this specific driver.


Performance

Connect the camera with Power DC in, instead of running on batteries. This will normally also prevent the camera from going into sleep mode.

Performance

Use a solid state drive (SSD) as location for the image destination folder.

Performance For Image Transfer use Move instead of Copy.

Troubleshooting

Always check that the camera, when connected via USB to your computer, is recognized by the Windows Operating system.
If Windows does not recognize the camera, then Qinsy won't either.
See Interfacing Notes for more details about this.

Troubleshooting

When the camera is disconnected or switched off while on-line, you must go off-line and on-line again in order to re-establish a connection.

Troubleshooting / Performance

Capturing interval is too short in order for Qinsy to store the images to disk and trigger the next photo which results in missing photos.

  • This is probably caused by the fact that also the RAW image file is stored, or that the jpg image resolution is too high.
    Select action Get device settings information and increase the Compression Level and / or decrease the Image Size.
  • Also make sure that RAW storage is disabled.
  • Finally, try to capture without auto focus being enabled.

Calibrate Latency

Notice that, due to the characteristics of digital cameras, there will always be a latency. This is the time difference between the moment of the capture command, and the timestamp of the captured image. The latency is often variable and depends on camera settings. E.g. if the camera is auto focusing, the latency can be up to 800 milliseconds! Under normal conditions the latency is small, around 100ms.

If exact and accurate timing is important for your application, you may use the following calibration procedure in order to try determining the camera latency:

  • Step 1)
    Use a Generic Display and add a General Item 'Time', with format 'HH:MM:SS.sss'. Important is to set the refresh rate of the display to 10Hz:

  • Step 2)
    Focus on your computer screen and take a picture of this display, using the Manual Capture command:

  • Step 3)
    View the image with your default image viewer, and compare the time in the Generic Display, with the time of the image, as displayed in the Information row in the driver's Camera menu.

    The difference in milliseconds can then be entered in the Node Setup menu.
    The GPS location and time, stored as EXIF Metadata in the image, will be corrected for every new captured image.
Camera Settings
  • Auto focus must be disabled. Sometimes the auto focusing fails, then camera keeps on trying, and when it already receives the next trigger, it may stop.
  • Please use a fixed focus lens e.g. f=20mm
  • Focus it to infinity, set the camera focus to "manual" and fix the focus ring on the lens by using a piece of tape (is very common in the photogrammetry).