OmniCal Camera Setup

Warning

OmniCal camera networks must use a separate network adaptor for all other network traffic.

Summary

1. Download Vimba or Vimba X for Windows.
2. Install Vimba / Vimba X to configure the cameras.
3. Network setup.
4. Verify camera connections.
5. Adjust exposure & focal length.

OmniCal Machine Vision (MV) system

This camera setup must be done before you run Designer.

Network setup

Warning

OmniCal MV cameras will use all the available network bandwidth. Therefore they must always remain on a dedicated physical network, separated from any other traffic. Sharing the camera switch with other devices or using network adaptor virtualisation cannot be supported, as any other traffic leads to dropped packets and potentially to disconnected cameras.

Note

• When Camera Discovery is enabled, machine vision cameras continuously capture images, and send them to the Director. This only affects the camera network, and not Disguise directly, however, it consumes CPU time processing these packets.
• Camera Discovery can be disabled explicitly in the Calibrator window and is also turned off automatically when the Calibrator and Plan windows are not open.

Network infrastructure

The OmniCal MV system is based on the GigE Vision (R) industry standard, which requires a bandwidth of 1 Gbit/s or higher. Camera capture speed scales with the available usable bandwidth. For example, on 10 Gbit/s setups, the discovery of MV cameras and the transmission of captured images will be much faster.

The MV cameras are powered via PoE, which must be provided either by the network switch or a PoE injector. The power requirement over PoE is quite low at 2.8W.

Ensure that all network infrastructure parts (switches, cables…) match the desired bandwidth and power specifications.

In the case of wired cables (as opposed to fibre), we recommend using at least Cat6 cables, because they are more reliable than Cat5e over longer distances or in the presence of electromagnetic interference (EMI).

Network adaptor settings

The following settings need to be set on the network adaptor on the Director server that connects to the switch with the cameras. You may need to update to the latest drivers to see some of these advanced options.

• Jumbo Frames: Enabled, with packet size (MTU) 8228 bytes or larger
  • e.g. 9000 or 9014, depending on whether the adaptor’s driver includes the packet header in the count or not
• DMA Coalescing: Disabled (since it may increase latency)
• Flow Control:
  • Can be left in the default setting. (In most network situations enabling it for Rx/Tx is beneficial, but it will not have an impact on GigEVision performance).
• Interrupt Moderation Rate: Extreme
• Transmit buffers: 256 bytes (or the closest low value the driver supports)
• Receive buffers: max setting available, e.g. 4096 bytes
  • This is because the adaptor will mainly need to receive many large packets.
• See here for further explanation.

Setting up the network adaptor

Using a 1 Gb port on the Director server for the camera communication should work fine. But a higher bandwidth port (e.g. 10 Gb) is preferred, as their max receive buffer size is larger. Some network adaptors may show some of the settings under an Advanced button. Other adaptors may not provide some settings at all: external network adaptors such as Promise SANLink3 may only offer the Jumbo Frames setting.

1. Navigate to the Network and Sharing Center and click to open the D - Media 10Gbit adaptor.
2. On the General tab, click to open Properties.
3. Enable the following settings and click Configure.
4. Select Jumbo Packet and assign it a value of 9014 bytes.
5. On the Advanced tab, select Performance Options.
6. Select Flow Control and click Disabled.
7. Set the Interrupt Moderation Rate to Extreme.
8. Select Receive Buffers and set it to 4096.
9. Select Transmit Buffers, set it to 256 and click OK.

Jumbo Packets

Jumbo Packets allow sending more data in a single packet, for example 9 kbyte instead of the default of 1500 byte. This reduces the number of packet headers being sent and increases the amount of actual data sent per second. Therefore Jumbo Frames increase the overall usable bandwidth, and also reduce the CPU usage on the sender and receiver’s side. Jumbo Packets can be configured for different packet / MTU sizes, typically around 8-9 kbyte. The value quoted by network adaptor drivers or switches can also vary, depending on whether they include any packets headers in the value or not.

Using Jumbo Packets can arguably make a network more fragile to interference, since dropped packets are larger, so resending them requires more work and data. So when using Jumbo Packets the system should always be set up to minimise dropped packets. In Designer you can use Camera Stats to check how your system performs regarding dropped packets and frames.

GigEVision protocol requirements

GigEVision was chosen as the basis for OmniCal machine vision cameras. It is an interface standard for high-performance industrial cameras on standard low-cost IP networking infrastructure. GigEVision comprises of several UDP-based protocols, that optimise for fast image transfer, but do not guarantee packet delivery to the receiver. For video data it uses a custom packet-resend algorithm, in which packets get dropped altogether if it’s not possible to get a full frame within a reasonable time. If the network is too saturated (e.g. camera bandwidth configured too high) or it experiences interference (other network devices on the camera switch) then some packets or even whole image frames may get dropped, cameras may time out, and in some cases cameras may even lock up and need to be rebooted.

The Network adaptor settings explained above are required for best performance of GigEVision cameras. In some circumstances it may be possible to use OmniCal successfully with different settings, but this will likely affect performance and reliability, and is therefore not recommended.

Switch Setup

1. Connect a PoE network switch with a bandwidth of 1 Gb/s or higher.
2. Enable jumbo frames/packets by setting the max packet size to the highest it will go (usually around 9k, see also above section).

OmniCal MV system setup (in Windows)

The Vimba / Vimba X software installs camera drivers, SDK, and the Vimba Viewer application used for testing and troubleshooting. For Designer releases since r27.7 please use Vimba X instead of Vimba. Vimba and Vimba X can be safely installed side-by-side on a system. This may be helpful if users need to switch between older and newer Designer releases (e.g. for rental servers).

For simplicity, the rest of this guide will just refer to “Vimba”.

1. Install Vimba or Vimba X for Windows SDK from here (under the Omnical section).
2. In the Vimba installer, select Application Development.
3. Keep install drivers checked and complete the installation as normal.
4. Hit Start and open Vimba Viewer
5. Plug your cameras in, if they are not already.
   1. They will appear in the Detected Cameras list in Vimba, in white.
   2. These may have a red lock icon on them if the camera is already opened elsewhere (see below).

Verify camera communication

1. Open Vimba and select a camera.
2. Press play button and verify images are streaming.

In case camera connections are lost, and replugged, the Vimba Viewer software should detect them again. In case they don’t you can press the refresh button in the top left corner.

Configuring cameras in Vimba

You can right-click or double-click on the cameras to see and adjust metadata of the camera.

This window also shows the Play button in the top left hand corner, on pressing this the camera image should appear in this window, this can be zoomed using the mouse scroll button.

Focus, aperture, and focal length

It’s easiest to adjust position, orientation, focus, and aperture (iris) while looking at the live preview in Vimba Viewer. Position and orient the cameras so they look at the object that is to be projected onto. Ideally, the whole camera image should be taken up by projected areas. It does not matter if the camera is mounted upside-down or right way up.

It is recommended to open the physical lens aperture (iris) as far as it can go (i.e. smallest F-Stop value). This will allow the most amount of light to enter the camera. You can then use the exposure time to control the total amount of light that hits the sensor for each frame. If the aperture is not fully open, then a longer exposure time is needed to achieve a similar overall brightness in the image. Any increased exposure time will also lead to slightly longer overall OmniCal capture times.

Adjust focus as needed by checking the image sharpness in Vimba Viewer. If the projected surface does not have many sharp visual features, then set up the projectors to output a suitable test pattern, so you can better assess the image sharpness. You may need to experiment with changing exposure time and focus settings, alternating between them, until you can clearly see a sharp image that is not too blown out (i.e. bright areas causing bloom/bleed in neighbouring camera pixels).

Note down the focal lengths used by each camera (they are written on the lens body); you will need these values later in Designer.

Brightness, Exposure Time, and other settings

Exposure time

Exposure time will heavily depend on the light levels in the calibration environment and the aperture setting of the lens. On the right-hand side you will see a value in milliseconds that allows you to calculate roughly the FPS the camera is producing. As mentioned above, longer exposure times will lead to lower FPS and thus slower OmniCal captures.

Other parameters do not need to be adjusted. Gain may need adjusting in exceptional circumstances, but in 99% of all cases adjusting aperture and exposure time is enough.

All

The “All” tab allows you to type in a filter pattern and search through all settings. This is useful for changing the DeviceUserID (see also below). Just type in the settings name and click Search. The DeviceUserID will be visible inside Disguise and is used to map OmniCal Plan cameras to physical cameras.

Renaming cameras in Vimba Viewer

We recommended adding unique names for each camera for easier identification within Designer. Follow these steps to set this up:

1. Close Designer.
2. Open Vimba Viewer.
3. Locate the setting “DeviceUserID” (not to be confused with a similar setting labelled “DeviceID” which cannot be changed).
4. Rename the camera as desired.
5. Press Enter and close this window.
6. Close Vimba Viewer when all cameras have been renamed and re-open Designer.
   • You may need to update the OmniCal Plan settings with the new camera device names.
   • Previous OmniCal captures may no longer be fully usable due to the camera name change.

Connecting to cameras in Designer

There is a separate program in the Disguise software called VimbaCamServer.exe which is used to discover and connect MV cameras on the network. VimbaCamServer will find cameras on any local network adaptor, just like Vimba Viewer. VimbaCamServer is a separate process that communicates with Designer via a TCP-based network protocol.

The Cameras collapsible widget contains network settings and camera lists for troubleshooting.

Camera discovery

The OmniCal Calibration editor configures and enables camera discovery on the network. Usually, VimbaCamServer is run locally on the Director server, so Designer can directly communicate with it. Set the Discovery Adaptor to the localhost “Loopback” adaptor, which is also the default. VimbaCamServer is launched automatically from within Disguise if this is set, and discovery is enabled. In this typical setup the network switch with the cameras needs to be connected directly to a dedicated network adaptor on the Director server.

Note

If you have many MV cameras on a network (especially if it is only 1Gbit/s), then not all cameras will be discovered immediately. They may appear one by one over the course of several seconds.

VimbaCamServer and Designer

The default “Loopback” adaptor essentially describes a local “network” connection between Designer and VimbaCamServer. The latter handles the actual camera GigEVision communication and captures images as PNG files for use in Designer. It communicates via the discovery adaptor with Designer, which in turn processes information and images within OmniCal. So the discovery adaptor is different to the adaptor that actually connects a machine to the camera switch.
Therefore, regarding network bandwidth it’s the network adaptor to the camera switch that matters, not the Loopback adaptor (since that is basically only limited by the PCI bus).

The VimbaCamServer can also be run separately, e.g. on a standalone computer. In that case, the Discovery Adaptor inside Disguise needs to be selected as the network port with which the Disguise server machine is connected to this other computer. The Director server does not need a direct connection to the cameras or the network switch they are on. In other words, the discovery adaptor needs to be set to the network adaptor that the camera server app is on. The VimbaCamServer can be anywhere as long as it can see and connect to the cameras and it can communicate with the Director.
Having VimbaCamServer on a different machine can reduce CPU load on the Director during OmniCal captures (it won’t have an impact when not capturing). However this requires manual process management on the other machine, so is not a recommended use-case.

List of discovered cameras

The Mobile Cameras button opens a list of cameras that have been discovered by Designer. The background colour for each camera row will indicate the state of the camera:

• Green: This means cameras are ok and receiving data from VimbaCamServer (with respect to the stats measuring incomplete frames between each receipt of stats).
• Red: This means there have been incomplete frames between the last read and the current read. The count of incomplete frames will continue to increase. The red colour will reset if there have been no incomplete frames between each read of the stats.
• Grey: This indicates the camera is disabled, e.g. due to incompatibility or licensing restrictions.
• Brown: This indicates the camera is disconnected / offline.

Camera network statistics

Camera Stats overview

The Camera Stats button opens a window that offers tools to enable camera streaming without capturing images to disk. This is useful to test and troubleshoot the network. The window contains a table with rows for every camera, which collect various statistics like captured and dropped packets or frames. The kind of statistics shown in the table can be configured.
It is possible to test streaming for all cameras or only a few selected cameras. This can help to identify whether an issue is specific to a certain camera or cable, etc. A certain amount of dropped packets can be tolerated in a properly set up camera network, but dropped frames should not appear, or only very rarely. These stats can be used to evaluate the impact of changes to e.g. network settings or the usable bandwidth (see next section). Checking the impact on dropped packets/frames here is much quicker than trying out a full OmniCal capture, which might time out half-way through.

How to use Camera Stats

1. Make sure to assign the physical OmniCal cameras to the cameras in the OmniCal Plan.
   If you see Camera Stats greyed out, then you have not finished this step, or no physical cameras have been discovered.
2. The columns display various camera stats and feedback of camera properties (such as IP, name).
   This widget only displays cameras that are used in the currently active Plan.
3. Right-click the widget header to show available columns and enable or disable them:
4. Click Start to enable streaming and stats feedback for a single camera. Click Stop to turn the stream off again.
5. Click Start All to enable streaming and stats feedback for all cameras.
6. The Open button in the Graph column opens a graph window that shows how the stats change over time.

Camera Stats columns

Visit this external link for additional information about each of the specific GigE stats.

Frames incomplete

Frames incomplete provides some feedback about the stability of the camera connections in VimbaCamServer.
This measurement indicates how many video frames were not completed for any reason, e.g.:

• not all packets were received, despite resend attempts
• failed to validate the frame data
• exceptions when handling frame data from Vimba API

See Troubleshooting below for information on how to resolve incomplete frames and other network issues.

BW [Bytes Per Second]

The network bandwidth in bytes/second that is assigned to this camera. This is an even share of the total MV bandwidth.

Camera Bandwidth

The field MV Network Bandwidth (Gbit/s) configures the total amount of usable bandwidth for OmniCal MV cameras. The network needs to reliably provide this bandwidth. Typically this should be set to a value about 80-90% of the theoretical bandwidth of the link between the camera switch and the server running VimbaCamServer (e.g. the Director). The default value is 0.85 Gbit/s, which should work for most 1G network setups. On a true 10G link to the Director a value of up to 8.5 Gbit/s should work.

If the network is not able to reliably provide this usable bandwith, e.g. due to traffic/interference from other devices, it will lead to dropped packets and potentially disconnecting cameras.
In this case it may help to reduce the MV Network Bandwidth value. Reducing the total bandwidth value will further slow down the capture, but allow for more room for packet re-sends, to avoid dropped frames. What value works will depend on the quality of the network setup or nature of any network interference.

Bandwidth management in Designer

Every time an OmniCal capture is started, Designer (or rather its sub-process VimbaCamServer) sets the bandwidth for each camera explicitly. Every camera gets an equal share of the total bandwidth set in Designer. For example when using 4 cameras, and 0.8 Gbit/s, every camera will be configured to use 0.2 Gbit/s.
This will overwrite any bandwidth setting configured externally, e.g. in Vimba Viewer.

The bandwidth also has an impact on the practical FPS and capture speed for each camera. The more cameras are connected, the longer each camera will need to stream a whole frame. Therefore, with equal bandwidth, more cameras result in reduced maximum FPS and longer capture time.

Troubleshooting

Camera has red lock icon in Vimba Viewer

This indicates that the camera is already opened elsewhere, for example another laptop running Vimba Viewer or Disguise Designer.
Camera access is exclusive; if you have a camera opened for capture in Designer, you will not be able to view it in Vimba and vice versa.

No image is displayed in Vimba Viewer

On older servers it may be worth trying to disable Jumbo Frames on the network adaptor that connects to the camera switch, or at least configuring them to a lower size. This has been observed in the past with legacy 4x4 pro servers, where Jumbo Frames with an MTU size over 2034 bytes was unable to get complete images from the cameras, due to packet loss. An alternative workaround would be to limit the packet size on the switch.
Use Vimba Viewer to verify the GVSP packet size setting is 2034 or below. This value is not set directly, but negotiated automatically between network adaptor, switch and cameras.

Network adaptor gets disabled in Windows after applying suggested settings

Try reverting the Interrupt Moderation Rate to the default value, which is Adaptive on most Intel adaptors. It may be necessary to re-enable the adaptor manually in Windows Advanced Network Settings.

Very slow image capture, dropped packets, incomplete frames, or cameras become unresponsive

1. Verify that the cameras are communicating using Jumbo Frames.
   • The reported GVSP packet size in Vimba Viewer must match the values you set for the network adaptor and switch (e.g. 9000 byte).
   • You can also check the GVSP value in the console_vimbacamserver.txt log file.
   • A value of 1500 indicates that Jumbo Frames were not enabled somewhere in the signal chain.
   • Any value between 1500 and 8000 indicates that some networking equipment in the signal chain is configured for smaller Jumbo Frames than desired. If this cannot be addressed, it may be necessary to reduce the total usable bandwidth in Disguise Designer (see Camera Bandwidth).
   • Any network switch that does not support Jumbo Frames must be removed from the signal chain.
2. Use the Camera Stats window to get more information about the network behaviour.
   • Test whether any network issues are specific to a certain camera or cable by streaming them individually.
     • If issues like dropped packets only occur with a certain camera, then try swapping cables and check other network equipment in that cameras signal path.
   • Add more cameras one-by-one to test whether problems only start after using a certain number of cameras.
     • If this is the case, it may be necessary to reduce the total usable bandwidth in Disguise Designer (see Camera Bandwidth).
     • Reducing the bandwidth will lead to slower image capture. But in a congested network this may still improve the capture performance, as it will lead to fewer dropped packets that then don’t need to be re-sent.
3. Ensure that the camera network is clean from any other interference.
   • Verify that the camera network is physically separate, with no other devices on it.
   • Use WireShark to monitor network traffic on the OmniCal network adaptor to spot any devices sending packets on this network. Devices such as lighting desks might flood the network with messages, or other machines might incorrectly use this network for copying data.
4. As mentioned in Network setup, VLANs and adaptor virtualisation are not officially supported, as they make it very difficult to guarantee the required bandwidth for the OmniCal cameras.
   • If a dedicated physical network is not available, then packets will be dropped whenever there is other traffic, which can lead to camera time outs during capture.
   • The likelihood of this happening can be reduced by reducing the total usable bandwidth in Disguise Designer (see Camera Bandwidth).
5. Try reverting the Interrupt Moderation Rate to the default value, which is Adaptive on most Intel adaptors.

Restarting unresponsive cameras

The easiest way to restart a camera is to disconnect and reconnect it from the PoE switch. For managed switches this can usually be done via a configuration GUI (e.g. browser interface) or even API commands.

Further Reading

GeniCam Network Card Performance Settings

Advanced Driver Settings for Intel® Ethernet 10 Gigabit Server adaptors