GigE Vision camera simulator in Docker: a testing guide

A container can act as a virtual GigE Vision camera, but only if its application implements the device side of the protocol. Putting an image generator inside Docker does not make it discoverable by acquisition software. This guide helps you plan a simulator that serves stored images or test patterns, select a workable network layout, and verify discovery, control, and streaming separately. Use it to test acquisition software before hardware arrives, then retain physical-camera testing for timing, image quality, and electrical behavior.

Decide which kind of simulation you need

Start with the interface your application must exercise. A folder reader tests image-processing code, while a virtual acquisition driver tests integration with a particular software stack. Neither necessarily creates a network device that another computer can discover.

A GigE Vision camera simulator must provide a device endpoint, not just consume one. Check the implementation's documented server capabilities before choosing a library or container image.

Choose the networked simulator when your application must discover a camera, read its features, start acquisition, and receive images through its normal transport layer. For a broader integration decision, use the camera acquisition software compatibility guide.

A simulator's usefulness comes from a clearly stated capability set. Do not treat successful streaming to one client as proof of standards compliance or compatibility with every receiver.

Define the endpoint contract before building the container

Write down what the simulated device must expose. At minimum, your client needs enough identification, feature information, and acquisition behavior to follow its normal startup sequence.

Your endpoint contract should describe:

• Device identity and how it remains stable across restarts.
• Network interface selection and the address presented to clients.
• Access to the device description and supported feature definitions.
• Image width, height, pixel format, and payload size.
• Acquisition start and stop behavior.
• Stream destination address, destination port, and packet configuration.
• Control ownership, disconnect handling, and supported recovery behavior.
• Features deliberately omitted from the simulation.

GigE Vision handles network control and image transport, while GenICam feature descriptions help software interpret device capabilities. An implementation may support only a subset of the features your application expects. Compare that subset with the application's actual startup reads and writes.

For example, an application might insist on configuring a trigger mode before acquisition. If the simulator supports only continuous acquisition, either provide an explicitly documented simulation mode or report that limitation. Silently accepting unsupported settings makes later hardware integration harder.

Obtain the runtime, server examples, documentation, and redistribution permissions from the manufacturer or its authorized distributors. Confirm that container deployment and automated test execution are permitted by the applicable license. Use only documented activation and licensing arrangements.

Choose networking that supports discovery and return traffic

Discovery, control, and image delivery are separate network exchanges. A client can discover an endpoint yet fail to open it, or open it successfully and receive no images.

GigE Vision discovery commonly uses UDP broadcast on port 3956. Container bridge networking and address translation can prevent a broadcast from reaching the intended interface. Discovery can also return an address that the client cannot subsequently reach.

For initial testing on native Linux, host networking can remove some namespace and address-translation variables. It also shares the host network namespace, so check port conflicts and limit exposure to your test network. Desktop container environments may introduce a virtual machine and different networking behavior; do not assume identical reachability.

A dedicated container address on the test network can also work when the platform and network policy support it. Verify host-to-container communication explicitly because some network driver arrangements require additional configuration for that path.

Bridge networking may be sufficient for a deliberately designed unicast setup. However, publishing a discovery port alone does not establish the complete control and stream path. Stream destination ports may be selected during configuration, and advertised addresses must remain meaningful to the receiver.

Use a small topology table during commissioning:

Keep firewall changes narrow and specific to the authorized test interfaces. The Linux discovery troubleshooting guide provides the closest companion workflow when the endpoint does not appear.

Make image content deterministic and self-checking

Begin with a generated pattern rather than a large image collection. A useful pattern includes an asymmetric marker, distinct image edges, and a changing frame counter. These make orientation errors, cropping, repeated frames, and stale buffers easier to identify.

Keep format negotiation separate from file decoding. A stored color image may need conversion before it matches the advertised output format. The transmitted buffer must agree with the declared dimensions, channel arrangement, pixel packing, and payload size.

For a basic test, use an unpacked monochrome format with one byte per pixel. Add packed formats, color formats, padding, and optional metadata only when both the server and receiver document support.

With a folder source, define these behaviors explicitly:

1. Sort filenames deterministically rather than relying on directory enumeration order.
2. Validate every file before reporting the endpoint ready.
3. Reject inconsistent dimensions or perform a documented conversion.
4. Choose whether the sequence loops, stops, or holds the final image.
5. Record the source filename and transmitted frame identifier in the server log.

A sequence of 200 images played at 20 frames per second repeats every 10 seconds. That repetition is useful for regression testing, but it is not independent production data. Include both acceptable and defective samples without using repeated playback as evidence of inspection accuracy.

For reproducible datasets and offline comparisons, follow the frame capture and storage workflow.

Calculate payload rate and buffering separately

Payload arithmetic helps you choose a sensible starting load. It does not establish the simulator's maximum speed or predict a physical camera's performance.

For an unpacked image without additional payload components:

Consider a generic test image measuring 1280 × 1024 pixels, with one byte per pixel, transmitted at 20 frames per second:

• Frame payload: 1280 × 1024 × 1 = 1,310,720 bytes.
• Payload rate: 1,310,720 × 20 = 26,214,400 bytes per second.
• Decimal payload rate: approximately 26.2 MB/s, or 209.7 Mb/s.
• A queue holding 32 complete images needs 41,943,040 bytes, approximately 41.9 MB, for image data alone.

These figures exclude packet headers, additional metadata, resend traffic, decoded source images, and application buffers. Actual network and memory consumption will be higher.

Pacing matters as much as the average rate. Sending each frame as a burst and then sleeping can produce the requested average frame rate while creating short periods of congestion. Prefer the implementation's documented pacing facilities, and record achieved rates rather than assuming requested rates were met.

At the example rate, one frame period is 50 ms. If the receiver regularly takes longer than that to release a buffer, a queue may hide the problem temporarily. Measure queue depth and frame age as well as frame count.

Validate discovery, control, and streaming in stages

Use a staged acceptance test so each failure has a narrow search area. Save the simulator configuration, client version, container image identifier, network layout, and logs with every test run.

1. Verify the process. Confirm that the server starts, loads its source images, binds the intended interface, and reports readiness.
2. Verify discovery. Check that the expected identity appears through the client's normal discovery method. Repeat with explicit interface selection where supported.
3. Verify feature access. Read image dimensions, pixel format, and payload size. Exercise supported writes and confirm the reported values afterward.
4. Verify acquisition. Start with a low frame rate and a single receiver. Check frame completeness, orientation, source sequence, and buffer release.
5. Verify lifecycle behavior. Stop acquisition, close the device, reconnect, and restart the container. Confirm that resources and control ownership are released correctly.
6. Increase the workload. Raise image size or frame rate one variable at a time while recording incomplete frames, CPU load, queue depth, and receive rate.

A client running beside the container proves less about routing than a client on another authorized test host. Include the second arrangement if remote acquisition is part of the intended deployment.

Do not assume one receiver's successful connection means multiple receivers can control the same endpoint simultaneously. If distribution to multiple clients is required, review the multicast receiver and control setup guide and confirm that the simulator implements the required behavior.

For incomplete frames or acquisition timeouts, use the packet, buffer, and MTU troubleshooting workflow rather than changing several network settings together.

Add controlled faults without confusing the diagnosis

Once baseline acquisition is repeatable, introduce failures that your own test endpoint can generate safely. Keep these tests isolated from production equipment and unrelated network traffic.

Useful cases include pausing image production, ending a sequence, stopping acquisition mid-run, restarting the endpoint, and refusing an unsupported feature write. Each case should have a documented expected client response.

For example, pause image production for longer than the client's configured receive timeout. Verify that the application reports a specific acquisition fault, releases its buffers, and follows its intended recovery policy. Distinguish this from packet loss: a server that produces no frame has not necessarily transmitted an incomplete one.

Record at least four observations for each test: the injected event, the simulator log, the receiver's reported condition, and the recovery outcome. Avoid adding malformed protocol traffic unless you have a separate, authorized protocol-validation plan and suitable tooling.

Container restart testing is especially useful for finding stale handles and uncontrolled reconnect loops. The acquisition stall recovery guide helps separate transport failures from application recovery defects.

Know what simulation cannot validate

A software endpoint cannot establish sensor noise, dynamic range, exposure behavior, rolling-shutter distortion, or optical resolution. Stored images preserve only the conditions captured when those images were created.

Likewise, host-generated timestamps do not automatically represent exposure timestamps. A simulated trigger callback is not evidence of electrical trigger latency, strobe alignment, or synchronization between physical devices.

Container scheduling, source decoding, memory copies, and the host network stack all influence delivery timing. That makes a simulator useful for stressing a receiver, but not a direct substitute for a camera when validating timing requirements. Use the frame arrival timing guide to distinguish image delivery measurements from camera timing questions.

The usual simulator-first approach is also wrong when your immediate uncertainty is glare, motion blur, depth of field, or defect contrast. Resolve those questions with representative parts and a physical imaging setup, using the lens and lighting test plan.

Physical-device passthrough is a different task from creating a virtual endpoint. Passing device nodes into a container does not turn that container into a GigE Vision server; the container camera device-node guide addresses that separate integration problem.

Choose physical cameras for the final validation stage

Select physical validation hardware for the inspection task, not merely because it resembles the simulator's image dimensions. The area scan cameras category and camera finder help narrow interface, shutter, sensor format, and mounting requirements.

The LS-CMR-0053 is a rolling-shutter GigE camera. It is a candidate when planning a physical acquisition test, subject to the imaging and timing requirements of your application.

The MV-CU020-90GC is a global-shutter color GigE camera. Evaluate its suitability separately from software compatibility; changing shutter or color requirements changes the imaging decision.

Compare the catalog attributes before choosing a physical test device.

All 2 share: Sensor size 1/1.7". Values as printed in each product's data sheet; open a part for its drawing and full specifications.

Neither product card establishes compatibility with a particular simulator or acquisition package. Confirm support using the relevant manufacturer's documentation, then repeat your acquisition acceptance tests with the actual device.

Use a release checklist before relying on the simulator

Keep the simulator reproducible enough that a failed test can be repeated without reconstructing the environment.

• Deployment: Pin the container image and runtime dependencies; document the legitimate licensing method.
• Identity: Define stable identifiers and avoid collisions when several simulated devices run together.
• Networking: Record interfaces, advertised addresses, discovery behavior, and stream destinations.
• Features: List supported operations and reject unsupported settings clearly.
• Images: Preserve a versioned dataset with known dimensions, formats, ordering, and expected outcomes.
• Performance: Record achieved payload rate, queue depth, incomplete frames, and resource consumption.
• Recovery: Test stop, reconnect, timeout, and restart behavior without unbounded retry loops.
• Limits: Mark which requirements still need physical camera, optical, or electrical testing.

Browse the available camera options when the software endpoint has passed its acceptance tests.

Next, use the camera configurator to plan the physical validation setup, or contact applications support with your image format, acquisition rate, client environment, and remaining test requirements.