Camera handle cleanup after Python script errors

A camera can work on the first run, then refuse to reopen after an image-processing exception. The cause may be an acquisition object still holding control, a buffer that was never returned, or a Python process that never actually ended. An empty discovery list, however, needs a different investigation. This troubleshooting sequence helps you establish explicit ownership, release resources after errors, and identify the failing stage before resetting hardware or replacing parts.

Start by identifying which operation fails

Record the first exception and the acquisition stage where it occurred. A later error during recovery can conceal the original problem. For example, indexing an empty device list explains why selection failed, but not why discovery returned nothing.

Separate the workflow into discovery, opening, acquisition, processing, and cleanup. Log entry and completion for each stage, together with the process ID and device identity.

For access conflicts involving acquisition hardware, start with detecting and handling frame-grabber access conflicts. If discovery succeeds but opening still fails, use the separate checks for GenTL opening failures after successful discovery.

Test for a surviving owner before changing settings

An editor window, interactive console, debugger, and Python process are not the same thing. A script can stop executing while its interpreter remains alive. Interactive environments may retain acquisition objects, callback registrations, or tracebacks that reference local variables.

Check these causes in order:

1. A console or notebook retained the object. Close the acquisition session explicitly, then restart that interpreter if necessary. Rerunning a cell does not establish that its earlier resources were released.
2. A background worker still owns acquisition. Request worker shutdown and wait for completion. Do not destroy its stream while it can still fetch or process buffers.
3. Another application has control. Close the diagnostic viewer or previous acquisition application normally. Confirm it has released the camera before testing your program.
4. A transport session has not expired yet. Some network-camera control sessions use heartbeat-based ownership. Follow the documented recovery behavior rather than repeatedly trying to open the camera.
5. Discovery or connection changed independently. Verify the loaded producer, device connection, and interface configuration. A stale handle is not the only explanation for an empty list.

Run the smallest acquisition test in a genuinely fresh process. If that works while the existing interpreter fails, retained application state becomes more likely. If both fail, widen the investigation.

Give each resource one owner and an exit path

Camera handle cleanup works best when one function owns the complete acquisition session. That function creates resources, uses them, and releases them before returning or propagating an exception.

A typical ownership chain includes a transport producer, an acquisition object, a stream, and borrowed image buffers. The exact object hierarchy depends on the SDK. Release children before their parents, following the documented sequence.

For a simple synchronous session, the intended exit sequence is usually:

• Finish or abandon processing of the current borrowed image.
• Return that buffer through the SDK's documented mechanism.
• Stop acquisition using the documented stream and camera sequence.
• Destroy or close the acquisition object, releasing device access.
• Release the transport manager after all its children are closed.

Do not treat deleting a Python variable as proof of hardware release. Reference cycles, retained exceptions, and background workers can extend object lifetimes. Garbage collection and object finalizers are not substitutes for explicit teardown.

Likewise, checking whether a variable exists does not establish that its handle is usable. The variable may reference an object whose acquisition stopped, whose device disconnected, or whose native resources were partly released.

Initialize session state deliberately. After teardown, discard the old session and recreate it through the documented initialization path. Do not reuse an acquisition object unless the SDK explicitly supports that lifecycle.

Structure exception-safe acquisition

Use the SDK's context managers when they document the required resource lifecycle. Otherwise, use try/finally or a cleanup stack. Register release operations immediately after successful resource creation, not at the end of the happy path.

The following Python example illustrates an adapter contract, not a specific camera library. Its method names must be mapped to the installed SDK's documented operations. The adapter's stop_if_active() must safely handle both incomplete startup and an already stopped session.

import logging
from contextlib import ExitStack

log = logging.getLogger(__name__)


def attempt_cleanup(label, operation):
    try:
        operation()
    except Exception:
        log.exception("Cleanup operation failed: %s", label)


def capture_once(adapter, device_identity, process_image):
    with ExitStack() as cleanup:
        transport = adapter.create_transport()
        cleanup.callback(
            attempt_cleanup, "close transport", transport.close
        )

        devices = transport.discover()
        identities = {device.identity for device in devices}
        if device_identity not in identities:
            raise RuntimeError("Requested camera was not discovered")

        acquirer = transport.open_acquirer(device_identity)
        cleanup.callback(
            attempt_cleanup, "destroy acquirer", acquirer.destroy
        )
        cleanup.callback(
            attempt_cleanup, "stop acquisition",
            acquirer.stop_if_active
        )

        acquirer.start()
        with acquirer.borrow_frame() as frame:
            process_image(frame.image)

Cleanup callbacks execute in reverse registration order. The borrowed-frame context exits before acquisition cleanup, including when processing raises an exception. Stopping acquisition then precedes destroying the acquisition object and closing its transport.

This pattern deliberately logs cleanup errors so that one failed cleanup operation does not prevent later release attempts. It also preserves an exception raised by acquisition or processing. In production, record cleanup failures as an unsuccessful session outcome, even when image processing completed normally.

The adapter still needs careful implementation. If a constructor allocates native resources and then raises, that constructor must unwind its partial allocation. An outer cleanup stack cannot release an object it never received.

A whole-file syntax error normally prevents that file from starting, so it does not create a new camera handle. A runtime error after opening the device does require cleanup. An interactive environment may already hold resources from an earlier execution.

Return buffers and stop workers before destroying objects

A fetched frame may borrow memory from the acquisition queue. Keeping its image view after returning the buffer can expose memory that the producer later reuses. Copy the image while the buffer is valid if processing must continue after its return.

For asynchronous processing, choose one explicit ownership policy:

• Copy the required image data, return the acquisition buffer, and send the copy to the worker.
• Transfer a documented buffer lease to the worker, which becomes responsible for returning it.

Do not mix these approaches without tracking ownership. Every successful buffer acquisition needs exactly one documented return operation.

If workers hold leases, request shutdown and wait for their completion before destroying the parent acquisition resources. Follow the SDK's stop and buffer-revocation ordering; it may differ from a simple synchronous example.

Treat output resources separately. A recording exception should release both the writer and camera session, without allowing one cleanup error to hide the other. The checks for empty recording files and writer cleanup cover the output side.

For failures that occur during sustained operation rather than after script errors, use isolating acquisition stalls under load. A queue that gradually fills is a different symptom from an immediate access conflict on reopening.

Investigate empty discovery independently

Never select device-list entry zero without checking that discovery returned a matching device. An empty collection is a discovery observation, not evidence that the camera was destroyed or permanently locked.

Select by a stable device identity where the producer exposes one. Enumeration order can change when devices reconnect or another camera becomes visible.

For an empty discovery list, check:

1. The expected transport producer loaded successfully.
2. The producer matches the interpreter's architecture and supported runtime.
3. The intended physical interface is present and available to the process.
4. Camera power and the relevant network or USB connection remain established.
5. Discovery was refreshed through the documented API after configuration changes.
6. A separate supported diagnostic application can discover the device when your application is closed.

Use manufacturer or authorized distributor sources for SDKs, drivers, and documentation. Do not change multiple software versions during the same isolation test.

If producer loading is uncertain, check GenTL producer-path handling in Python. If the device is missing only under a particular account or runtime, follow camera SDK discovery and operating-system access checks where that operating system applies.

A diagnostic application restoring access does not prove which operation fixed it. It may initialize an interface, refresh discovery, change state, or simply run after a control timeout. Record what changes instead of making that application part of every startup sequence.

Verify recovery with controlled error injection

Test cleanup deliberately before integrating image display, recording, or a larger inspection pipeline. Begin with a bounded session that opens the selected camera, captures an image, and closes normally.

Then raise a deliberate exception inside image processing. The expected behavior is that the buffer is returned, cleanup completes, the original exception remains visible, and a subsequent session can reopen the device.

A useful bench sequence is 20 normal sessions followed by 20 sessions with an injected processing exception. Attempt a fresh open after every session. Keep the same interpreter alive for this test to expose retained objects that a process restart might conceal.

This is a debugging check, not a reliability qualification. Repeat under representative processing load and the actual deployment runtime after the simple test passes.

Record discovery count, selected identity, open outcome, cleanup errors, and elapsed time for each stage. Use a monotonic clock for durations. Do not add an arbitrary sleep until logging establishes a documented timing requirement.

Also test an exception after opening but before acquisition starts. That catches cleanup code which only works after successful streaming. Test startup failure through a supported method rather than pulling connections on an operating machine.

Check interface compatibility before replacing hardware

A software ownership error is not a reason to replace a camera or interface card. Consider hardware changes only after logs show a connection, compatibility, or capacity problem independent of cleanup.

For GigE acquisition planning, the LS-CMR-0053 camera is a catalog camera candidate. The LS-FGB-0004 host-interface card is a catalog interface candidate. Neither product substitutes for explicit session teardown.

Browse area scan cameras through the camera finder when the inspection needs a different camera interface. Compare frame grabbers through the accessory finder when checking the host acquisition path.

Before ordering, verify the camera interface, supported producer, operating system, interpreter architecture, and required host connection. A shared category does not establish compatibility between every camera and card.

Use a short release-and-recovery checklist

Before considering the issue resolved, confirm the following:

• One session owner: one code path controls creation, acquisition, and teardown.
• Immediate cleanup registration: each acquired resource has a release action before later operations can fail.
• Explicit buffer ownership: borrowed images are returned once, and retained data is copied or leased correctly.
• Worker shutdown: no thread or callback can access an object after destruction begins.
• Original exception preserved: cleanup errors are logged without replacing the initial traceback.
• Discovery checked: an empty list produces a diagnostic message, not an indexing error.
• Repeated reopening verified: both normal and injected-error sessions release access.
• Documented recovery only: resets and reconnect procedures follow the device documentation and machine operating requirements.

If the camera still cannot reopen from a fresh process, collect the smallest reproducer, lifecycle log, software versions, and interface details. Send those through application support before replacing hardware. For a new acquisition setup, start with the camera configuration step and verify the complete interface path.