FalcoCV — Industrial Machine Vision Framework

FalcoCV is a modular machine vision environment for industrial automation. It combines a workflow-driven tool pipeline with real-time image processing, inspection, depth/3D analysis and camera acquisition, plus a web-based HMI for operator dashboards.

FalcoCV is under active development: interfaces and job formats may change between releases.

Highlights

• Workflow engine — chain tools in an explicit execution order; the list order is the contract and connections feed each tool's inputs. Jobs are saved as .cvj files.
• Vision toolset — acquisition, image enhancement, segmentation, template and shape matching, code reading, measurement, line/circle fitting, deep-learning inspection and 3D analysis.
• Depth + 3D - depth/range loading, the native .fcd LZ4 container, point clouds, plane fitting and a 3D viewer with world-space overlays. See docs/DEPTH_FORMATS.md and docs/3D_CONVENTIONS.md.
• Fixture system — per-image coordinate transforms; tools work in fixture-relative coordinates.
• Vector overlays — annotations are mathematical primitives rendered only by visible viewers; source pixels are never modified.
• Scripting + debugger — editor, breakpoints, stepping and variable/watch panels. HMI runtime objects can be passed to job Python Scripts through the shared context / engine_context; see docs/HMI_CONTEXT.md.
• HMI designer + web server — design operator dashboards, deploy them to a FastAPI server and open them from any browser.
• Communications runtime — generic devices and tags in the .hmi project, editable from the HMI Designer, with local and live signal monitors, Omron, Beckhoff ADS, Siemens S7 and ADLINK DASK I/O drivers, plus Modbus TCP and OPC UA clients and server runtimes. Drafts can be saved with missing fields; Deploy and Signal Monitor require a complete configuration. See docs/COMMS.md.
• Persistent workspace — window geometry, dock placement, splitter sizes and table column widths are restored between runs. Use View > Reset all views to return the current workspace to its defaults.
• Camera acquisition — GigE Vision and USB3 Vision cameras through Harvesters and a vendor GenTL producer.

Screenshots

Generated with the bundled demo project by scripts/capture_readme_screenshots.py. The 3D view uses a synthetic point cloud; the HMI dashboard image is the Designer preview with representative runtime values.

Vision Editor Workflow, result image and per-tool timing for the demo inspection job.	3D analysis Interactive point-cloud viewer with a world-space ROI and world-coordinate navigation.
HMI Designer Job slots, dashboard widgets, live preview and deployment controls.	HMI dashboard Operator view with verdict, measurement and runtime log (preview data).
Communications servers Explicit Modbus TCP and OPC UA mappings exposed from HMI communications tags.

Install

FalcoCV is distributed as a wheel for Windows x86_64 and Linux x86_64 (CPython 3.13.x):

python -m pip install falcocv

Python 3.13 is the only supported version for this release. The native kernel ships inside the wheel, so no compiler is needed. On Windows, install the Microsoft Visual C++ 2015-2022 Redistributable (x64); ONNX Runtime and the native kernel use that runtime. On platforms without a wheel, pip builds it from the sdist and needs Python 3.13.x, CMake 3.20+ and a C++17 compiler. On Linux the wheels target glibc 2.34+ (Ubuntu 22.04+, Debian 12+, RHEL 9+), which is what PyQt6 requires. GigE and USB3 Vision cameras only need the vendor GenTL producer (.cti file); the Harvesters integration is installed by default.

From source

Requires CPython 3.13.x:

git clone https://github.com/jaesc/falcocv.git
cd falcocv
python -m pip install ".[dev]"

PLC communications

The optional PLC extra installs the Omron, Beckhoff and Siemens libraries:

python -m pip install "falcocv[plc]"
# from source:
python -m pip install -e ".[plc]"

It includes aphyt (Omron), pyads (Beckhoff ADS) and python-snap7 (Siemens S7). Driver imports are lazy, so the rest of FalcoCV can be used without these dependencies. Write verification is opt-in; when enabled, write_retries adds verification retries, while without verification the driver trusts the library response and never retries. A device configuration may be saved incomplete (for example Siemens without a host) and completed later; only Deploy and execution require every field and tag address. Hardware-specific prerequisites:

• Omron: reachable NJ/NX controller; no persistent dictionary file is used.
• Beckhoff: TwinCAT ADS route configured in the router. The optional ip_address is only needed for Linux or routed/NAT networks. TcAdsDll.dll comes from TwinCAT or %APPDATA%/FalcoCV/native/beckhoff/.
• Siemens: PUT/GET enabled on S7-1200/1500 and non-optimized DBs for absolute addressing. S7-300/400 use absolute addressing normally. The python-snap7 3.x package is pure Python and needs no DLL.
• ADLINK: install the DASK SDK for the card model on Windows x64. FalcoCV detects the runtime automatically; if it is not on the system path, use the Driver setup actions to select the SDK folder or place the DLLs in %APPDATA%/FalcoCV/native/adlink/. Test card confirms that the card can be registered. Digital and analog DASK tags are supported.
• Beckhoff: the Driver setup panel checks pyads and TcAdsDll.dll and always reminds you to configure the ADS route. Test connection verifies the route and target AMS Net ID before deploying.

For Modbus TCP and OPC UA clients/servers install the protocol extra:

python -m pip install "falcocv[protocols]"

The Servers tab exposes existing tags through explicit Modbus TCP or OPC UA mappings. Modbus has no authentication; OPC UA server security is anonymous in this first release, so keep both on trusted networks.

Models

ONNX models are not bundled with the package; they are downloaded on first use to:

• Windows: %APPDATA%/FalcoCV/models
• Linux: $XDG_DATA_HOME/FalcoCV/models (or ~/.local/share/FalcoCV/models)

The splash screen shows progress and startup waits until the models are ready. To pre-download or repair them:

falcocv download-models
# or the dedicated entry point
falcocv-download-models

To use an existing local bundle instead (offline or pre-provisioned machines), point FALCOCV_MODELS_DIR at the folder that contains the model files.

Downloads come from a GitHub Release. Override the base URL to use a mirror:

export FALCOCV_MODELS_URL="https://mirror.example.com/falcocv/models-v1"

Run

The web dashboard is served at http://localhost:8000; HMI pages are available at http://localhost:8000/?id=<project_id>.

Demo

examples/demo_inspection.cvj locates a bracket with Shape Match, uses it as a fixture, counts the two through-holes with Blob Detector and measures their distance with Measurement:

git clone https://github.com/jaesc/falcocv.git
cd falcocv
falcocv run examples/demo_inspection.cvj --output results.json

The dataset is 14 synthetic images (10 OK, including cosmetic scratches and stains; 4 NG: missing/blocked/extra hole and wrong hole spacing). Image generation, the trained job and the annotated results are scripted and reproducible — see examples/README.md. All of it is original CC0 artwork.

Architecture

src/falcocv/
├── core/        Workflow engine, VisionImage, overlays, ROI, model resolver
├── tools/       Vision tools
├── ui/          PyQt6 widgets, viewers, ROI editors, HMI designer
├── web/         FastAPI server, HMI workers, dashboard
├── comms/       devices, tags, PLC/protocol drivers, Modbus/OPC UA servers
├── main.py      Vision Editor
├── hmi_designer.py  standalone HMI Designer
├── cli.py       `falcocv` / `python -m falcocv`
└── version.py   single source of truth for the package version

cpp/kernel/      Native kernel (no OpenCV)
tests/           Pytest suite

FalcoCV is Python-first: tools and algorithms use OpenCV/NumPy unless a measured benchmark shows a real end-to-end win. A small C++ kernel collects only those performance-critical hot paths, so the native surface stays minimal and does not shape the tool API. It has no OpenCV dependency; OpenCV is provided by opencv-python.

See ARCHITECTURE.md for the module layout and benchmarks/ for the performance harness.

Development

git clone https://github.com/jaesc/falcocv.git
cd falcocv
python -m pip install -e ".[dev]"
pytest -q --ignore=tests/test_trainer_equivalence.py

An editable install builds the native kernel through scikit-build-core. To run directly from the source tree, build the kernel once and point PYTHONPATH at src:

build_kernel.bat          # Windows
./build_kernel.sh         # Linux/macOS

set PYTHONPATH=src        # Windows
export PYTHONPATH=src     # Linux/macOS
python -m falcocv

Native kernel

build_kernel.bat            :: configure + build + deploy to cpp/bin
build_kernel.bat --rebuild  :: clean cache first
build_kernel.bat --clean    :: remove artifacts

./build_kernel.sh

Requirements: CMake 3.20+, a C++17 compiler, pybind11 and OpenMP. On Windows, Visual Studio 2022 with the "Desktop development with C++" workload is enough. No OpenCV build is required.

Testing

pytest -q --ignore=tests/test_trainer_equivalence.py

Targeted runs:

pytest -q -m integration   # headless workflows, jobs, barcode, depth
pytest -q -m ui            # offscreen Qt config dialogs / main window
pytest -q -m web           # FastAPI / HMI endpoints
falcocv self-test          # installation smoke test (also works from a wheel)

The suite covers the workflow engine, vision tools, UI (offscreen Qt) and web/HMI endpoints. The trainer-equivalence test needs the optional training toolchain (torch/timm) and is excluded.

License

FalcoCV is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

FalcoCV is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for the full text.