User Guide
Getting Started
The first step is to connect cameras to GigE or GigE Vision network adapters.
Install Pylon software. For non GigE Vision adapters Pylon will install filter drivers.
Verify or setup IP addresses of the cameras. See Network Setup for more details.
Optionally cameras can be checked with Pylon Viewer.
If several cameras need to share the same adapter, bandwidth load must be estimated. See Bandwidth Control for more details.
Note
For really high-performance note that the performance intermediate routers and hubs can affect the system operation
Network Setup
Basler GigE cameras can run on 100Mbit and 1000Mbit adapters. If high performance is expected, the camera can to be connected directly to dedicated GigE or GigE Vision adapter on the target PC.
Note
Running on 100Mbit requires tight bandwidth control
For non GigE Vision adapters Pylon will install filter driver. This can be verified by going to Control Panel-Network Connections-Connection Properties. Make sure filter driver is present and activated on the correct adapter. Cameras won’t work without filter driver.
When Basler cameras are connected they do get IP addresses. Even so, pylon IP Configurator should be invoked to verify that cameras get correct addresses.
Begin by verifying that adapters have correct subnets. Then see that cameras have IP addresses from those subnets. Use static addresses if automatic or dhcp does not work.
Note
Max Receive and Transmit Buffers to 512 or 2048 or as high as the adapter allows. Do not allow the adapter to negotiate the netwoek speed.
Pylon Viewer
pylon Viewer from Basler allows to view existing connected cameras, open them, change their parameters and test different modes of operation.
Among other things pylon Viewer can be used to stress test network setup. Open and run cameras at high framerates and monitor message log for error messages. Also notice read-only counters at Stream Parameters-Statistics. See if failed frame count stays at zero.
Bandwidth Control
Although theoretical throughput of Gigabit network is around 120MB/s, it should be expected that cameras can transfer maximum of 80-100MB/s of image data.
Multiple cameras will share the available bandwidth
More bandwidth can be added to a system by using multiple adapters
Adapter performance can be improved by enabling Jumbo Frames and disabling Interrupt Moderation
Limiting camera framerate is an easy way to do bandwidth management. See Triggering Control for more details.
For standard GigE adapters jumbo frames (or large packets) can be enabled. This will increase the capacity of the system. Go to adapter properties and click on Configure, then go to Advanced tab and search for jumbo frames. Not all adapters and routers support jumbo frames.
At the same time Packet Size in camera driver must be adjusted to match size of jumbo frames (see transport layer parameters)
However it would work best only on short direct connections. Over longer distances large packets can make things worse.
GigE vision adapters will be already optimized for this, no additional setup needed.
When there are several cameras on the same adapter, the sum of load across all cameras must not exceed total line throughput. However, even then there may be packet conflicts - if cameras grab images simultaneously and try to transfer them as quickly as possible.
The following parameters may be adjusted to avoid packet conflicts (more details in transport layer parameters):
Packet Size - making it larger (as allowed by network adapter) will reduce load. But conflicts on larger packets will take longer to resend.
Inter-Packet Delay - may be increased to reduce load.
Frame Transmission Delay - may be differentiated across several cameras.
Bandwidth Reserve - reserve bandwidth to handle packet resend and transmission collisions
Bandwidth Assigned - read-only parameter tells exactly how much bandwidth a camera is using. Have a sum of this for all cameras on the same adapter.
Note
In a system were you do not need maximum performance setting the Bandwith Reserve to a value between 10 to 30% will handle improve the robustness and can be recommended.
The number of collision may increase having multiple hw triggered cameras.
Triggering Control
By default camera will be in freerun mode without framerate limit. Scorpion may trigger images at defined slower rate, but camera would still stream images as fast as possible under given image size, exposure, etc. Network may get unnecessarily overloaded.
Note
The framerate is explicitly specified by:
Enable Acquisition Frame Rate - Enables framerate control.
Acquisition Frame Rate - Defines max number of images to deliver in one second.
Another option to limit network overload is to use Hardware or Software camera trigger. Trigger is enabled with TriggerMode parameter set to on, then Trigger Source can define either Hardware Line or Software trigger.
Some Basler cameras provide both AcquisitionStart and FrameStart trigger groups.
Note
They both relate to triggering parameters, but it was observed that if both groups are present, then AcquisitionStart group is ignored by camera.
Therefore either both groups or only FrameStart should be set.
Using Software Trigger
Software Trigger will not be as fast as Hardware trigger but it can be used as an alternative to camera freerun mode, especially when network load must be reduced. In order to use software trigger the following parameters must be checked:
Trigger Mode is on
Trigger Source is set to Software
Software trigger will be automatically issued with Scorpion’s Grab command (via python or via Scorpion actions). Python example:
ExecuteCmd('Grab','')
Alternatively software trigger can be issued directly to the camera via setProperty. Python example:
GetCamera("0").setProperty("softwareTrigger", 1)
Heartbeat and Camera Reconnect
When network connection is lost and then later restored, camera is able to reconnect automatically.
GevHeartbeatTimeout parameter from TransportLayer section specifies frequency by which pylon checks if connection to camera is still alive. Whenever it is discovered that connection is gone, Scorpion camera driver receives a notification and closes the camera.
Then, if it is desirable that camera gets reopened automatically, the following parameters must be set:
- ReconnectOnLoss (General):
Enable camera reconnect attempts when heartbeat timeout disconnects the camera. Default is True.
- ReconnectTryCount (General):
Number of attempts to reopen the camera when connection is lost. Default is 0, which means infinite retry count.
- ReconnectWaitSeconds (General):
Period in seconds to wait before attempting next reopen. This a float value, i.e. it can be fractional. Default is 10s.
- ReconnectSendMsg (General):
If True, driver will send a message to Scorpion System Log, that camera got disconnected or reconnected. Ensure that corresponding data is set in TCP/IP (Services) tab of Scorpion: Active is checked and ListenPort matches to ReconnectMsgPort
- ReconnectMsgPort (General)
When messages are sent to Scorpion (see above) this is the port that Scorpion must be listening to.
- GevHeartbeatTimeout (TransportLayerControl):
Adjust heartbeat timeout (in milliseconds). Default is 3000ms. Camera connection loss will not be detected sooner than this timeout elapses.
If camera was grabbing images before the connection was lost, the grabbing will resume after connection is restored.
Note
Monitor Scorpion console messages from camera and System Log. Connection loss, reconnect attempts and succeful reconnect are printed in the log.
Action Command
Action command is another way to trigger one or several cameras over tcp/ip by using PTP protocol.
Note
Not all cameras support Action Command - only those with Action Control section present in camera parameters.
In order to use Action Control, set corresponding parameters for each camera and then use python script on one of the cameras to trigger image acquisition.
Parameters:
key
group
Corresponds to ActionDeviceKey and ActionGroupKey of the camera.
There must be an exact match between key/group and ActionDeviceKey/ActionGroupKey.
Default=1.
mask
Corresponds to ActionGroupMask of the camera.
ActionGroupMask of the camera and mask of the python command are evaluated by AND and must amount to nonzero value.
Logically mask enables to define and activate different subgroups of cameras within a group.
Default=1.
ip
Target address where command is directed.
Use specific address, address of a subnet(s), or skip altogether if commands needs to be sent to all cameras on all available interfaces, for example:
10.0.0.32 - send to one particular address
10.0.0.255 - send to all cameras on 10.0.0.0/255.255.255.0 subnet
255.255.255.255 - send everywhere
Default = 255.255.255.255
For example:
key/group/mask of Camera1=1/1/1
key/group/mask of Camera2=1/1/2
ActionCommand=1/1/2 would trigger Camera2.
ActionCommand=1/1/3 would trigger both cameras.
ActionCommand=1/1/4 would trigger neither.
ActionCommand=1/2/1 would trigger neither.
For more information refer to Basler website.
Python command example:
cam= GetCamera("0")
#send to one particular camera
cam.executeCmd('set','ActionCommand= {key=1; group=1; mask= 1; ip=10.0.0.32}')
#just send to all reachable cameras.
#use default values key/group/mask=1 and ip=255.255.255.255
cam.executeCmd('set', 'ActionCommand')
#send to all reachable with mask= 3
cam.executeCmd('set', 'ActionCommand={ mask=3;}')
Note
Monitor camera console for ActionCommand error messages.
Scorpion Continous Mode
Scorpion Vision 8 and higher supports continous mode. This mode is implemented in order to reduce the overhead when using high framerates. Scorpion can handle framerates up to 100..250 frames per second. The actual number depends upon camera type and interface used. The continous mode eliminates the need and overhead to issue a Grab command for each image. This means that Scorpion only concentrates to receive the images as fast as they flow into the PC.
Activate continous mode for the first camera:
GetCamera("0").setProperty("continous", 1)
DeActivate continous mode for the first camera:
GetCamera("0").setProperty("continous", 0)
Camera Configuration in Scorpion
Camera parameters can be configured via configuration dialog or by using python scripts.
OK will write parameter values into configuration file and will close camera, which will be reopened immediately. Any parameters can be changed (as opposed to python scripts, or Apply where for example Width or Height cannot be changed).
Apply will keep the dialog open, but the changed values will be written to camera. Changes to the parameter state (i.e. becoming read-only, etc) will be reflected in the list. Finally, in order to keep the changes, the dialog must be closed with OK.
Most parameters and their descriptions are provided from camera by GeniCam interface. Parameters in General group are Scorpion driver specific. There are still some other parameters accessible only via python script which serve also as commands.
Since camera parameters are different from model to model, and even new generations of the same model, below there are only the basic GeniCam related parameters.
General
Scorpion driver specific parameters.
Property |
Description |
|---|---|
InhibitPylonTerminate |
If enabled then Pylon terminate function will not be called. Enable when using several pylon drivers in the same profile, for example Basler Runner together with Area Scan gige or firewire cameras. |
Log level |
Level 0 suppresses all messages. Level 1 issues error and warning messages. Levels 2,3 issue diagnostic messages. |
BufferCount |
Number of buffers used for grabbing. More buffers will consume more memory. On the other hands buffers will guard against loss of image due to occasional image processing slowdown. Mimumum recommended count of buffers is 2. |
Reconnect |
When set to True camera driver will try to periodically reopen camera in case of network connection loss. |
Heartbeat |
Number of milliseconds between network connection checks. This parameter tells how quickly network loss is detected by camera when there is one. Setting to too low value will add to network congestion. |
ImageFormat
Property |
Description |
|---|---|
UseBGR |
This should be enabled for color cameras, otherwise blue and red will be swapped in the final image. |
TestImageSelector |
This enumeration provides a list of the available test images. Selecting a test image from the list will enable the test image. |
AnalogControls
Property |
Description |
|---|---|
GainAuto |
The gain auto function automatically adjusts the Auto Gain Raw parameter value within set limits, until a target average gray value for the pixel data from Auto Function AOI1 is reached. |
All_GainRaw |
Sets the ‘raw’ value of the selected gain control. The ‘raw’ value is an integer value that sets the selected gain control in units specific to the camera. |
All_BlackLevelRaw |
This value sets the black level control. |
GammaEnable |
Enables the gamma correction. |
Gamma |
This feature is used to perform gamma correction of pixel intensity. |
AOI
Property |
Description |
|---|---|
Width |
Set the width of the area of interest in pixels. |
Height |
This value sets the height of the area of interest in pixels. |
OffsetX |
This value sets the X offset (left offset) for the area of interest in pixels, i.e., the distance in pixels between the left side of the sensor and the left side of the image area. |
OffsetY |
This value sets the Y offset (top offset) for the area of interest, i.e., the distance in pixels between the top of the sensor and the top of the image area. |
BinningVertical |
Sets the number of binned adjacent vertical pixels. Their charges will be summed and reported out of the camera as a single pixel. |
BinningHorizontal |
Sets the number of binned adjacent horizontal pixels. Their charges will be summed and reported out of the camera as a single pixel. |
AcquisitionTrigger
Property |
Description |
|---|---|
TriggerMode |
This enumeration sets the trigger mode for the selected trigger. |
TriggerSource |
This enumeration sets the signal source for the selected trigger. |
TriggerActivation |
This enumeration sets the signal transition needed to activate the selected trigger. |
ExposureAuto |
The exposure auto function automatically adjusts the Auto Exposure Time Abs parameter value within set limits, until a target average gray value for the pixel data of the related Auto Function AOI is reached. |
ExposureTimeRaw |
This value sets an integer that will be used as a multiplier for the exposure timebase. The actual exposure time equals the current exposure time raw setting times the current exposure time base abs setting. |
ExposureTimeAbs |
This float value sets the camera’s exposure time in microseconds. |
ExposureTimeBaseAbs |
This float value sets the time base (in microseconds) that is used when the exposure time is set with the ‘raw’ setting. |
AcquisitionFrameRateEnable |
This boolean value enables setting the camera’s acquisition frame rate to a specified value. |
DigitalIO
Property |
Description |
|---|---|
LineX_LineMode |
This feature controls whether the physical Line is used to Input or Output a signal. When a Line supports input and output mode, the default state is Input to avoid possible electrical contention. Line Mode can take any of the following values: input- the selected physical line is used to input an electrical signal; output- the selected physical line is used to output an electrical signal. |
LineX_LineDebouncerTimeRaw |
Sets the raw value of the selected line debouncer time. |
LineX_LineFormat |
This feature controls the current electrical format of the selected physical input or output Line. Line Format can take any of the following values:
|
OutX_LineInverter |
This boolean value enables the inverter function for the selected line. |
OutX_LineStatus |
This boolean value indicates the current logical state for the selected line at the time of polling. |
OutX_LineSource |
This enumeration selects the internally generated camera signal (source signal) for the selected line. |
OutX_UserOutputValue |
This boolean value sets the state of the selected user settable output signal. |
Note: ‘X’ in property name must be substituted with the line number (0,1,2), e.g. Line1_LineMode.
TimerControls
Property |
Description |
|---|---|
TimerDurationTimebaseAbs |
This float value sets the time base (in microseconds) that is used when a timer duration is set with the ‘raw’ setting. |
TimerDelayTimebaseAbs |
This float value sets the time base (in microseconds) that is used when a timer delay is set with the ‘raw’ setting. |
TimerX_TimerDelayRaw |
This value sets an integer that will be used as a multiplier for the timer delay timebase. The actual delay time equals the current timer delay raw setting times the current timer delay time base abs setting. |
TimerX_TimerDurationRaw |
This value sets an integer that will be used as a multiplier for the timer duration timebase. The actual duration time equals the current timer duration raw setting times the current timer duration time base abs setting. |
TimerX_TimerTriggerSource |
This enumeration sets the internal camera signal used to trigger the selected timer. |
AutoFunctions
Property |
Description |
|---|---|
AutoTargetValue |
The target average gray value may range from nearly black to nearly white. Note that this range of gray values applies to 8 bit and to 16 bit (12 bit effective) output modes. Accordingly, also for 16 bit output modes, black is represented by 0 and white by 255. |
AutoGainRawLowerLimit |
Lower limit of the Auto Gain (Raw) parameter |
AutoGainRawUpperLimit |
Upper limit of the Auto Gain (Raw) parameter |
TransportLayer
Property |
Description |
|---|---|
GevHeartbeatTimeout |
This value sets the heartbeat timeout in milliseconds. |
Packet Size |
StreamChannel0_GevSCPSPacketSize. If using other packet size than default (1500), unless you have already set the packet size for your network adapter during the installation of the Pylon AreaScan software, check the documentation for your adapter to determine the maximum packet size (sometimes called “frame” size) that the adapter can handle. Many adapters can handle what is known as “jumbo packets” or “jumbo frames”. These are packets with a maximum size of 16 kB. Once you have determined the maximum size packets the adapter can handle, make sure that the adapter is set to use the maximum packet size. |
Packet Delay |
StreamChannel0_GevSCPD. Sets delay in ticks between packets sent by the camera. Applies to the selected stream channel. Increasing the inter-packet delay will decrease the camera’s effective data transmission rate and will thus decrease the network bandwidth used by the camera. In the current camera implementation, one tick=8ns. |
Frame Transmission Delay |
StreamChannel0_GevSCFTD. Sets a delay in ticks (one tick = 8 ns) between when a camera would normally begin transmitting an acquired frame and when it actually begins transmission. This parameter should be set to zero in most normal situations. If you have many cameras in your network and you will be simultaneously triggering image acquisition on all of them, you may find that your network switch or network adapter is overwhelmed if all of the cameras simultaneously begin to transmit frame data at once. The frame transmission delay parameter can be used to stagger the start of frame data transmission from each camera. |
Bandwidth Reserve % |
StreamChannel0_GevSCBWR. Used to reserve a portion of the assigned bandwidth for packet resends and for the transmission of control data between the camera and the host PC. The setting is expressed as a percentage of the Bandwidth Assigned parameter. For example, if the Bandwidth Assigned parameter indicates that 30 MByte/s have been assigned to the camera and the Bandwidth Reserve parameter is set to 5%, then the bandwidth reserve will be 1.5 MByte/s. |
Bandwidth Reserve Accumulator (RO) |
StreamChannel0_GevSCBWRA. A software device called the bandwidth reserve accumulator is designed to handle unusual situations such as a sudden EMI burst that interrupts a frame transmission. If this happens, a larger than normal number of packet resends may be needed to properly transmit a complete frame. The accumulator is basically an extra pool of resends that the camera can use in unusual situations. |
Actual Bandwidth (RO) |
StreamChannel0_GevSCBWA. Indicates the bandwidth in bytes per second that will be used by the camera to transmit frame and chunk feature data and to handle resends and control data transmissions. The value of this parameter is a result of the packet size and the inter-packet delay parameter settings. Note: Sum of bandwidth for all cameras on the same NIC must not exceed 125MB/s on a gigabit network. Otherwise frame overruns may occur. |
Actual Bandwidth (RO) |
StreamChannel0_GevSCDCT. Indicates the actual bandwidth (in bytes per second) that the camera will use to transmit the image data and chunk data (if any) in each frame given the current frame size, chunk feature settings, and the pixel format setting. |
Frame Max Jitter (RO) |
StreamChannel0_GevSCFJM. If the Bandwidth Reserve Accumulation parameter is set to a high value, the camera can experience a large burst of data resends during transmission of a frame. This burst of resends will delay the start of transmission of the next acquired frame. The Frame Max Jitter parameter indicates the maximum time in ticks (one tick = 8 ns) that the next frame transmission could be delayed due to a burst of resends. |
Setting properties with Python
All properties accessible through configuration dialog can also be read via python. Most of them can be modified as well.
The exception is read only properties. Some properties are always in read only state, the others are read only when camera is open (e.g. width or height). The latter can be modified via configuration dialog.
There are two api functions to access properties in Python:
executeCmd - the preferred method. It allows to set/get any value regardless of its type.
getProperty/setProperty - a method compatible with all previous versions of Scorpion. Operates with integer values only.
Setting a parameter:
cam=GetCamera('0')
cam.executeCmd('set', 'Framerate=7.7') # set framerate to new float value = 7.7
cam.setProperty('Framerate', 8) # set new framerate value, integer values only
#below all three commands achieve the same result.
cam.executeCmd('set', 'FrameStart_TriggerActivation=Falling Edge')
cam.executeCmd('set', 'FrameStart_TriggerActivation=1') #See note below
cam.setProperty('FrameStart_TriggerActivation', 1)
Reading a parameter:
cam=GetCamera('0')
cam.executeCmd('set', 'Framerate=7.7') # set first
print cam.executeCmd('get', 'Framerate') # prints "7.7"
print cam.getProperty('Framerate') # prints "7"
Note. For enumeration properties (comboboxes in dialog) either entry name or sequential number of the entry must be used. The entry name must exactly match the one displayed in configuration dialog. E.g. above sample has Falling Edge as a second value in enumeration list (therefore - 1). This approach is not recommended, but is a workaround for setProperty
Ini file management
Ini file contains all camera related settings that can be changed by the user. Default ini file location is in Hardware folder under the current profile location. Ini file is read from when camera is opened and written to when camera settings dialog is closed with OK.
Ini file contains data sections named after port number under which the camera is opened. This way one ini file can contain data for several cameras. Moreover, it allows, by switching camera ports, to quickly assign different sets of parameters to the camera. Sections contain generic camera name to prevent assigning parameters to completely different camera. If such is the case, those parameters will be ignored on reading.
There is also a possibility to use alternative ini file, in a different location, under a different name. It is important to specify such name before camera is opened, since several parameters, like Width, Height, etc. cannot be changed after camera is opened. Therefore alternative ini file setting will be ignored if done after camera is opened. When activated, it will be used instead of default ini file.
To specify alternative ini file name:
activate BeforCameraOpen event in Scorpion Actions
call executeCmd(‘set’, ‘IniFile=new_ini_file’)
Ini files can be exported - to have a copy of parameters for that particular camera. Likewise, ini file can be imported, with a limitation that parameters, fixed on open (Width, Height, etc), will not be changed.
executeCmd(‘set’, ‘ExportIni=exported_ini_path_and_name’)
executeCmd(‘set’, ‘ImportIni=imported_ini_path_and_name’)
To verify, which file is currently active or default:
executeCmd(‘get’, ‘DefaultIniFile’)
executeCmd(‘get’, ‘ActiveIniFile’)
File import and export is also available in settings dialog via toolbar buttons on top. In the status bar at the bottom the current active ini file is displayed.
Parameter aliases
There are property names which provide aliases for common functions or serve as commands to the driver.
Property |
Description |
|---|---|
LogLevel |
debug level, [0..3] |
Framerate |
maps to AcquisitionFrameRate on USB camera or AcquisitionFrameRateAbs on GigE camera |
Exposure |
maps to ExposureTimeAbs |
Shutter |
maps to ExposureTimeAbs |
Gain |
maps to All_GainRaw |
Brightness |
maps to All_BlackLevelRaw |
Gamma |
scaled by 1000, e.g. to set gamma=0.75 call setProperty(‘gamma’, 750). getProperty likewise will return a scaled value |
Python only properties
Some properties are available only via python script. A property can be an actual command.
Property |
Type |
Description |
|---|---|---|
LogDebugView |
get/set |
debug level [0..3] |
Continous |
set |
boolean (1 or 0), video stream continuous mode, passing all frames to Scorpion regardless of grab command |
DeviceReset |
set |
performs camera reset |
FeatureSave |
set |
save camera parameters into a file (just filename given as parameter, will be located in ‘Hardware’) |
FeatureLoad |
set |
load previously saved parameters from a file |
IniFile |
get/set |
specify ini file to be used as the main ini file. The default will not be used. Must be called before camera open. |
DefaultIniFile |
get |
return the default ini file |
ExportIni |
set |
export all camera parameters into a file (given as an argument in executeCmd |
ImportIni |
set |
import camera parameters from a file (given as an argument in executeCmd). Will not change width/height etc. |
Flush |
set |
remove all currently waiting buffers |
MemoryUsed |
get |
memory currently used by driver (debug only) |
FrameCount |
get |
number of received frames (debug only) |
BuffersInQueue |
get |
number of buffers currently in pylon queue (debug only) |
Example Device Reset - setProperty:
GetCamera('0').setProperty('DeviceReset', 1) #in this case the value 1 is not important.
# the device reset may take some time de
Example Device Reset - executeCmd:
GetCamera('0').executeCmd('set', 'DeviceReset=1')
Example Save all feature nodes:
GetCamera('0').executeCmd('set', 'FeatureSave=FeaturesCam0011.ini')
Example Load all feature nodes:
GetCamera('0').executeCmd('set', 'FeatureLoad=FeaturesCam0011.ini')
Chunk Mode
In Chunk mode at the beginning of each frame some additional information is attached - timestamp, framecounter and more.
To enable chunk mode - open camera properties dialog and enable ChunkModeActive under ChunkDataStreams section. Press Apply. Then some individual chunk parameters can be enabled/disabled. Not all parameters are the same accross different cameras.
Accessing chunk data can be done by two ways - via configuration dialog or via python script:
execCmd= GetCamera('0').ExecuteCmd
print "timestamp=", execCmd('get', 'ChunkTimestamp')
print "frameCount=", execCmd('get', 'ChunkFramecounter')
print "triggerCount=", execCmd('get', 'ChunkTriggerinputcounter')
The particular names of chunk parameters can be obtained from configuration dialog ChunkData section.
Note
Chunk data ChunkFramecounter or ChunkTriggerinputcounter can be used to verify that no frame is missed. These are counters that will be advanced by 1 with each new frame.