Source snapshot of github.com/Scottcjn/npu-linux-kit@edee964

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI (software-only)
+
+# Every module in this kit is an application layer on top of the open-xdna
+# NPU stack (IRON/mlir-aie + Peano + a real XDNA1 NPU + amdxdna driver).
+# None of that toolchain or hardware exists on a normal GitHub-hosted
+# runner, so this workflow does NOT and CANNOT verify:
+#   - any camera/*.py effect actually running on the NPU
+#   - camera/kernels/blur3x3.cc compiling (needs the Peano AIE2
+#     cross-compiler and aie_api headers)
+#   - any of the measured FPS/latency numbers in camera/README.md
+#
+# What IS hardware-independent and checked here:
+#   - every Python file parses (byte-compiles) cleanly
+#   - the host-side pip requirements (opencv, onnxruntime, numpy,
+#     ml_dtypes, pyvirtualcam) install cleanly on Linux/x86_64
+#   - each camera/*.py module imports up through all of ITS OWN
+#     host-side deps and fails only at `import aie.iron` (i.e. the NPU
+#     toolchain boundary), never earlier on a host-side bug. If a
+#     module fails on anything other than a missing `aie` module, that
+#     is a real bug this CI will catch.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  syntax-and-host-deps:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Byte-compile all Python sources (syntax only, no NPU/aie needed)
+        run: python -m compileall -q camera
+
+      - name: Install host-side requirements (no NPU stack involved)
+        run: pip install -r requirements.txt
+
+      - name: Import each camera module up to the NPU-toolchain boundary
+        run: |
+          set -e
+          fail=0
+          for f in camera/*.py; do
+            echo "--- $f ---"
+            out=$(python3 "$f" 2>&1) && { echo "ran to completion (unexpected without hardware, but not a failure)"; continue; }
+            if echo "$out" | grep -q "ModuleNotFoundError: No module named 'aie'"; then
+              echo "OK: fails only at the expected NPU-toolchain (aie) boundary"
+            else
+              echo "$out"
+              echo "FAIL: $f errored before reaching the aie import boundary"
+              fail=1
+            fi
+          done
+          exit $fail

.gitignore

@@ -0,0 +1,11 @@
+cam_sample_*.png
+__pycache__/
+*.pyc
+.venv/
+blur_*.png
+cam_sample_*.png
+_scene.png
+bgblur_*.png
+*.onnx
+_*.png
+_*.py

COMMERCIAL.md

@@ -0,0 +1,42 @@
+# Commercial & Proprietary Licensing
+
+`open-xdna` is released under the **GNU Affero General Public License v3.0 (AGPLv3)** —
+see [`LICENSE`](LICENSE). The AGPLv3 is a strong network-copyleft license: if you modify
+this software or use it to provide a service over a network (including AI inference APIs,
+SaaS pipelines, or cloud-side compute offloading), AGPLv3 §13 requires you to make the
+complete corresponding source of your application available to its users under the same
+terms.
+
+## When you need a commercial license
+
+The AGPLv3 is ideal for open-source and research use. You should obtain a **separate
+commercial / proprietary license** if you want to:
+
+- Integrate `open-xdna` (or its techniques as implemented here) into a closed-source
+  product or internal service **without** the AGPLv3 source-disclosure obligation;
+- Offer a hosted/SaaS service built on this code without publishing your backend;
+- Ship it inside proprietary firmware, an appliance, or an OEM product;
+- Obtain a warranty, indemnification, or a support/SLA arrangement.
+
+This is a standard open-core dual-licensing model: the same code is available under
+AGPLv3 (free, copyleft) **or** a commercial license (paid, no copyleft obligations).
+
+## Acquisition & partnership
+
+Inquiries about commercial licensing, technical partnership, or acquisition of this
+work and the underlying research are welcome.
+
+**Contact — Elyan Labs**
+Scott Boudreaux
+Lake Charles, Louisiana, USA
+Web: https://elyanlabs.ai
+
+Please include your intended use, deployment scale, and whether you are seeking a
+per-deployment license, a site license, or an acquisition discussion.
+
+---
+
+*Copyright © 2026 Scott Boudreaux / Elyan Labs. Original scripts, documentation, and
+benchmark harnesses in this repository are the copyrightable work being licensed. AMD's
+XDNA/XRT and IRON/mlir-aie toolchains are licensed separately (Apache-2.0 WITH
+LLVM-exception) and are not redistributed here.*

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program 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 the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

NOTICE

@@ -0,0 +1,16 @@
+npu-linux-kit
+
+Copyright (c) 2026 Scott Boudreaux / Elyan Labs LLC
+
+This program is free software: you can redistribute it and/or modify it
+under the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option)
+any later version. The full text is in LICENSE.
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+Commercial licensing
+--------------------
+The copyleft terms above are not the only option. If they do not suit your
+use, a separate commercial licence is available from the copyright holder.
+Contact: scott@elyanlabs.ai

README.md

@@ -0,0 +1,77 @@
+---
+license: agpl-3.0
+tags:
+- elyan-labs
+- llm-inference
+- npu
+- linux
+- edge-inference
+---
+
+> Source snapshot of [github.com/Scottcjn/npu-linux-kit](https://github.com/Scottcjn/npu-linux-kit), also on [GitLab](https://gitlab.com/elyan-labs/npu-linux-kit) with full history. Code only: nothing here runs on Hugging Face infrastructure.
+
+<div align="center">
+
+# 🧰 npu-linux-kit
+
+**Practical applications for the AMD XDNA NPU on Linux** — the things the NPU is *actually* good at,
+in one kit. Built on the [open-xdna](https://github.com/Scottcjn/open-xdna) gen-1 (XDNA1 / Phoenix)
+bring-up.
+
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPLv3-blue.svg)](LICENSE)
+[![Dual License: Commercial](https://img.shields.io/badge/License-Commercial-green.svg)](COMMERCIAL.md)
+
+</div>
+
+---
+
+## Why
+
+AMD's NPU is underused on Linux: the official LLM stack targets XDNA2, and the NPU's real strengths
+(**low-power, conv/vision, batchable compute, offload**) aren't packaged into usable Linux apps. This
+kit does that — each module plays to a **measured** NPU strength, and the status of each is stated
+honestly (no "coming soon" dressed up as done).
+
+## Modules
+
+| Module | What it does | NPU fit | Status |
+|--------|--------------|---------|--------|
+| **[camera/](camera/)** | Real-time webcam effects → a **v4l2 virtual camera** (Zoom/OBS/browser) | conv/vision — its native strength | ✅ **working** (edge-stylize) |
+| camera/ — background blur | Sharp foreground + blurred background (real MODNet segmentation) | conv/CNN | ✅ **working** (clean CPU blur + real seg; NPU blur path experimental) |
+| **[embeddings/](embeddings/)** | Batch sentence/RAG embeddings, offloaded from CPU/iGPU | batchable matmul → amortizes dispatch | 🔬 candidate |
+| **[audio/](audio/)** | Wake-word / real-time denoise | the NPU's classic edge job | 🔬 candidate (untested) |
+| **[ggml-backend/](ggml-backend/)** | XDNA backend for ggml/llama.cpp | foundational enabler | 🚧 planned (biggest lift) |
+
+## Featured: camera effects (working today)
+
+Live webcam → NPU effect → virtual camera, **measured on a Ryzen 7 8845HS (XDNA1)**:
+
+- Full per-frame conv/colorspace pipeline: **220 FPS @1080p / 451 FPS @720p** (incl. host DMA round-trip).
+- In the live daemon the NPU effect adds **~2 ms/frame at ~6.6 W** — end-to-end is **camera-capture-bound**, never NPU-bound. So there's large headroom for heavier effects (segmentation).
+- Outputs to a **v4l2loopback** device — any app sees `NPU Camera`.
+
+```bash
+# (after the open-xdna NPU stack is up + this kit's requirements installed)
+sudo modprobe v4l2loopback video_nr=10 card_label="NPU Camera" exclusive_caps=1
+python3 camera/npu_camera_fps.py                                  # FPS feasibility gate
+python3 camera/npu_camera_daemon.py --loopback /dev/video10 --stream-frames 0   # live → virtual cam
+# then pick "NPU Camera" in Zoom/OBS/your browser
+```
+
+## Requirements
+
+A working **XDNA NPU stack** (XRT + amd/xdna-driver + IRON/mlir-aie + Peano) — see
+[open-xdna](https://github.com/Scottcjn/open-xdna) for the bring-up. Plus host deps:
+`pip install -r requirements.txt` (opencv-python-headless, pyvirtualcam, numpy, ml_dtypes) and
+`v4l2loopback` for the virtual camera.
+
+## Honesty / scope
+
+Verified on **XDNA1 (Phoenix)**, Ubuntu 25.10 / kernel 6.17. The **camera module is real and
+measured**; the other modules are marked candidate/planned and make **no working claims** until built.
+Research/community project, not a production stack.
+
+## License
+
+AGPLv3 + commercial dual-license — see [LICENSE](LICENSE) and [COMMERCIAL.md](COMMERCIAL.md).
+© 2026 Scott Boudreaux / Elyan Labs.

amd_dev_community_showcase.md

@@ -0,0 +1,41 @@
+TITLE (one line):
+npu-linux-kit: practical AMD XDNA NPU apps for Linux — a working NPU webcam-effects daemon (220 FPS pipeline), plus an honest roadmap
+
+CATEGORY: Showcase  (also fits Projects & Demos)
+
+----- BODY -----
+
+**TL;DR.** A kit of practical Linux applications for the AMD XDNA NPU — built on my open-source
+gen-1 (XDNA1 / Phoenix) bring-up. The first module is a **working real-time NPU webcam-effects
+daemon** that outputs a v4l2 virtual camera (so Zoom/OBS/browsers use it). The other modules
+(background-blur, embeddings, audio, a ggml backend) are on a roadmap and **clearly marked as
+candidate/planned — no working claims until built.** Repo: https://github.com/Scottcjn/npu-linux-kit
+(foundation: https://github.com/Scottcjn/open-xdna)
+
+**Why.** AMD's NPU is underused on Linux — the official LLM stack targets XDNA2, and the NPU's real
+strengths (low-power, conv/vision, batchable compute, offload) aren't packaged into usable Linux
+apps. This kit does that, one measured module at a time.
+
+**Working today — NPU webcam effects.** Live camera → NPU conv/colorspace effect (edge-stylize:
+rgba2gray → 3×3 filter2d → threshold → blend) → **v4l2loopback virtual camera**. Measured on a
+Ryzen 7 8845HS (XDNA1), Ubuntu 25.10 / kernel 6.17:
+
+- Full per-frame pipeline incl. host DMA round-trip: **220 FPS @1080p, 451 FPS @720p** (7–32× headroom over 30fps).
+- In the live daemon, the NPU effect adds **~2 ms/frame at ~6.6 W** — end-to-end is **camera-capture-bound** (~15 FPS on a USB webcam), *never* NPU-bound.
+
+So the NPU runs the effect essentially for free, leaving the CPU/iGPU idle — exactly the low-power
+offload role it's built for. There's huge headroom for heavier effects.
+
+**Roadmap (honestly marked):**
+- **Background blur** — the marquee "Studio Effects" feature; needs a segmentation model on the NPU. The headroom says feasible; not built.
+- **Embeddings** — batch sentence/RAG embeddings; matmul-heavy + batchable → amortizes the NPU's dispatch overhead. Candidate.
+- **Audio** — wake-word / denoise; the NPU's classic edge job, but **untested here** — listed as a candidate, not a claim.
+- **ggml backend** — an XDNA backend for ggml/llama.cpp; the foundational enabler. Biggest lift.
+
+**Honesty / scope.** Verified on XDNA1 (Phoenix). The camera module is real and measured; the rest
+make no working claims. Research/community project, not a production stack. The kit builds on
+open-xdna, where I also filed the bring-up issues/PRs upstream (amd/xdna-driver #1447/#1448/#1449,
+plus an mlir-aie discussion on the AIE2 vector ISA).
+
+Feedback very welcome — especially from anyone on Phoenix/Hawk Point hardware who wants NPU camera
+effects on Linux. 👉 https://github.com/Scottcjn/npu-linux-kit

amd_devcloud_credits_answer.md

@@ -0,0 +1,30 @@
+How do you plan to use your AMD GPUs on the AMD Developer Cloud?
+
+I maintain open-source AMD-stack projects: **open-xdna** (the first-gen XDNA1 / Phoenix NPU brought
+up on Linux end-to-end with a 100% open stack — XRT + amd/xdna-driver + IRON/mlir-aie + Peano) and
+**npu-linux-kit** (practical NPU apps, including a working webcam-effects daemon with real-time
+background blur). From that work I've filed upstream contributions to amd/xdna-driver (issue #1447,
+docs PR #1448, code PR #1449) and a Xilinx/mlir-aie discussion. I'd use Instinct GPUs on the
+Developer Cloud for the **datacenter→client pipeline** the full AMD stack is built for:
+
+1. **Train & quantize models for NPU deployment.** Fine-tune and INT8-quantize lightweight
+   vision/segmentation models (MODNet-class portrait matting, and the conv stages for my NPU camera
+   kit) on MI300X, then deploy them to the Ryzen AI NPU via IRON/mlir-aie — the "train on Instinct,
+   infer on XDNA" loop. My kit currently runs segmentation on the CPU; this is how I move it onto AMD
+   silicon end-to-end.
+
+2. **Settle a live, community-reviewed open question: ROCm vs Vulkan GEMM.** I measured that on a
+   Ryzen 8845HS, CPU prompt-prefill beats the Radeon 780M iGPU ~2.6x on llama.cpp's Vulkan/RADV
+   backend (while decode favors the iGPU). A community reviewer rightly questioned whether that's a
+   hardware result or an immature open Vulkan GEMM path; my on-silicon re-test showed it's robust to
+   ubatch/length tuning, which points at the Mesa/RADV Q4_K GEMM kernels rather than the hardware.
+   The clean way to settle it is to run the **identical workload on a mature ROCm/hipBLAS GEMM path**
+   and profile achieved FLOPS/occupancy with rocprof — isolating software-stack vs hardware. Instinct
+   GPUs on the Dev Cloud let me do exactly that, then port my hand-authored matmul/conv/prune kernels
+   to ROCm and publish honest heterogeneous-partitioning guidance for Ryzen AI builders.
+
+3. **LLM inference & quantization research.** Benchmark and quantize LLMs (Gemma/Qwen) on MI300X to
+   feed the integrated-NPU deployment work, and validate my non-bijunctive prune/collapse experiments
+   at scale.
+
+All outputs are open-source, continuing the public track record above (github.com/Scottcjn).

audio/README.md

@@ -0,0 +1,5 @@
+# audio (candidate — untested)
+
+Wake-word spotting / RNNoise-class real-time denoise on the NPU. **Status: design-domain, NOT yet
+tested.** This is the NPU's classic edge use case, but no audio has been run on it in this project
+yet — listed honestly as a candidate, not a claim.

camera/README.md

@@ -0,0 +1,61 @@
+# camera — NPU webcam effects for Linux
+
+Real-time webcam effects on the AMD XDNA NPU, output as a **v4l2 virtual camera** so any app
+(Zoom, OBS, browsers) can use it. This is an open-source take on the "Studio Effects" idea that
+Windows ships on the NPU and Linux lacks.
+
+## Status
+
+- ✅ **edge-stylize** (`--effect edge`) — rgba2gray → 3×3 Laplacian → threshold → blend.
+- ✅ **blur** (`--effect blur`, `blur_pipeline.py`) — NPU 3×3 box-blur conv, **449 FPS @720p**, verified
+  (row variance 16256→255 on a 1px test pattern; `test_blur.py`). v1 is grayscale + a single 3×3 pass (mild blur).
+- ✅ **background blur** (`npu_background_blur.py`) — clean, working end-to-end:
+  - **Segmentation = real**: MODNet via onnxruntime (`--onnx modnet.onnx`) → accurate person cutout
+    (~136 ms/frame CPU). Center-ellipse placeholder only if no model is given.
+  - **Blur = clean, on the NPU**: a **custom AIE kernel** (`kernels/blur3x3.cc`, bound by `blur_plane.py`)
+    gives a correct, artifact-free unity-gain Gaussian — int32 acc + int16 coeffs + `>>12` + `[0,255]`
+    clamp, where the stock `filter2d` saturated bright pixels. Enable with `--npu-blur`.
+  - **Composite**: sharp foreground + blurred background, feathered edges.
+  - **Perf (measured):** with `--npu-scale 4`, the NPU blur runs at reduced res (bokeh is low-frequency,
+    so visually identical) and is **free within the frame budget**. End-to-end runs at the **camera's full
+    rate — ~16 FPS on this USB webcam, which is the capture ceiling, NOT compute-bound** (NPU blur + MODNet
+    seg both keep up; passes 1/2/3 all hit ~16 FPS). A faster camera yields more FPS with the NPU keeping up.
+    `--npu-scale 4` is the validated config; higher scales can ERT-timeout (AIE dimension-sensitive).
+  - Get MODNet: `curl -L -o modnet.onnx https://huggingface.co/Xenova/modnet/resolve/main/onnx/model.onnx`
+  - Still test: `python3 npu_background_blur.py --image scene.png --onnx modnet.onnx [--npu-blur]`
+
+## Measured (Ryzen 7 8845HS, XDNA1, Ubuntu 25.10 / kernel 6.17)
+
+`npu_camera_fps.py` — full per-frame pipeline incl. host DMA round-trip:
+
+| resolution | ms/frame | FPS | headroom @30 |
+|---|---|---|---|
+| 640×480 | 1.02 | **985** | 32× |
+| 1280×720 | 2.21 | **451** | 15× |
+| 1920×1080 | 4.54 | **220** | 7× |
+
+`npu_camera_daemon.py` — live `/dev/video0` → NPU effect → `/dev/video10` virtual cam:
+the NPU effect adds **~2 ms/frame (~6.6 W)**; end-to-end is **camera-capture-bound** (~15 FPS on a
+typical USB webcam), **never** NPU-bound. The NPU is essentially free here.
+
+## Usage
+
+```bash
+# 1) create the virtual camera (once per boot)
+sudo modprobe v4l2loopback video_nr=10 card_label="NPU Camera (open-xdna)" exclusive_caps=1
+
+# 2) feasibility gate (optional)
+python3 npu_camera_fps.py
+
+# 3) run the daemon: live camera -> NPU effect -> virtual cam
+python3 npu_camera_daemon.py --loopback /dev/video10 --stream-frames 0   # 0 = run until Ctrl-C
+
+# 4) in Zoom/OBS/your browser, select camera "NPU Camera (open-xdna)"
+```
+
+Notes:
+- Needs the XDNA NPU stack up (see [open-xdna](https://github.com/Scottcjn/open-xdna)); run under the
+  IRON venv. `/dev/accel` access typically needs `sudo` or the `render` group.
+- Set `MLIR_AIE_DIR` if your mlir-aie checkout isn't at `~/open-xdna/mlir-aie` (the daemon imports the
+  `edge_detect` IRON pipeline from there).
+- Without `--loopback`, the daemon runs a capture-vs-NPU **benchmark** and saves a before/after sample.

camera/blur_pipeline.py

@@ -0,0 +1,351 @@
+# NPU blur design (adapted from edge_detect). GAIN FIX 2026-06-24: add_weighted alpha 32767->16384
+# (unity on uniform 64). KNOWN: per-channel round-trip + multipass still adds diagonal color speckle
+# + mild under-gain on bright values. A clean NPU blur needs a PURPOSE-BUILT single-channel/RGBA
+# design (no rgba2gray round-trip, no add_weighted) — see camera/README 'NEXT'.
+# vision/edge_detect/edge_detect.py -*- Python -*-
+#
+# This file is licensed under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# (c) Copyright 2024-2026 AMD Inc.
+"""Vision edge-detect pipeline -- ``@iron.jit`` design.
+
+  shim --> rgba2gray --> filter2d (3x3 Laplacian) --> threshold -->
+                                                     gray2rgba+addWeighted --> shim
+
+The filter2d worker reuses an inner Buffer holding the constant Laplacian
+kernel.  The gray2rgba+addWeighted worker combines the thresholded edge
+map with the original RGBA input (forwarded via ``inOF_L2L1``).
+"""
+
+import argparse
+import sys
+
+import numpy as np
+
+import aie.iron as iron
+from aie.iron import (
+    Buffer,
+    CompileTime,
+    In,
+    ObjectFifo,
+    Out,
+    Program,
+    Runtime,
+    Worker,
+    kernels,
+)
+from aie.iron.controlflow import range_
+from aie.utils.hostruntime.argparse import (
+    device_from_args,
+    add_compile_args,
+)
+from aie.utils.hostruntime.cli import run_design_cli
+from aie.utils.verify import assert_pass
+
+
+@iron.jit(aiecc_flags=["--alloc-scheme=basic-sequential"])
+def blur(
+    in_tensor: In,
+    _b_unused: In,
+    out_tensor: Out,
+    *,
+    width: CompileTime[int] = 1920,
+    height: CompileTime[int] = 1080,
+):
+    height_minus_1 = height - 1
+    line_width = width
+    line_width_in_bytes = width * 4  # 4 channels (RGBA)
+
+    line_bytes_ty = np.ndarray[(line_width_in_bytes,), np.dtype[np.uint8]]
+    line_ty = np.ndarray[(line_width,), np.dtype[np.uint8]]
+
+    rgba2gray_line_kernel = kernels.rgba2gray(line_width=line_width)
+    filter2d_line_kernel = kernels.filter2d(line_width=line_width)
+    threshold_line_kernel = kernels.threshold(line_width=line_width, dtype=np.uint8)
+    gray2rgba_line_kernel = kernels.gray2rgba(line_width=line_width)
+    # add_weighted operates byte-wise over the flattened RGBA buffer, so its
+    # "line width" is the full RGBA stride in bytes.
+    add_weighted_line_kernel = kernels.add_weighted(
+        line_width=line_width_in_bytes, dtype=np.uint8
+    )
+
+    in_of_l3l2 = ObjectFifo(line_bytes_ty, name="inOF_L3L2")
+    in_of_l2l1 = in_of_l3l2.cons(7).forward(depth=7, name="inOF_L2L1")
+    out_of_l1l2 = ObjectFifo(line_bytes_ty, name="outOF_L1L2")
+    out_of_l2l3 = out_of_l1l2.cons().forward(name="outOF_L2L3")
+
+    intermediate_depths = [4, 2, 2]
+    of_intermediates = [
+        ObjectFifo(line_ty, depth=intermediate_depths[i], name=f"OF_{i + 2}to{i + 3}")
+        for i in range(3)
+    ]
+    of_local = ObjectFifo(line_bytes_ty, depth=1, name="OF_local")
+
+    # Laplacian edge-detect kernel: cross stencil with -16384 center, 4096 edges.
+    # Gaussian blur: int16 coeffs >>8 -> int8 [[1,2,1],[2,4,2],[1,2,1]] (sum 16), then >>4 (SRS_SHIFT-8)
+    # = exact unity-gain weighted mean. (A box can't be unity-gain here: 9/16 under-gains.)
+    filter_kernel_buff = Buffer(
+        np.ndarray[(3, 3), np.dtype[np.int16]],
+        name="kernel",
+        initial_value=np.array(
+            [[256, 512, 256], [512, 1024, 512], [256, 512, 256]], dtype=np.int16
+        ),
+    )
+
+    workers = []
+
+    def rgba2gray_fn(of_in, of_out, rgba2gray_line):
+        elem_in = of_in.acquire(1)
+        elem_out = of_out.acquire(1)
+        rgba2gray_line(elem_in, elem_out, line_width)
+        of_in.release(1)
+        of_out.release(1)
+
+    workers.append(
+        Worker(
+            rgba2gray_fn,
+            [in_of_l3l2.cons(), of_intermediates[0].prod(), rgba2gray_line_kernel],
+        )
+    )
+
+    def filter_fn(of_in, of_out, filter_kernel, filter2d_line):
+        # 3-line stencil over height rows.  Top/bottom borders duplicate the
+        # adjacent row; the steady-state middle uses real (i-1, i, i+1).
+        for _ in range_(sys.maxsize):
+            # Top border
+            elems_in_pre = of_in.acquire(2)
+            elem_pre_out = of_out.acquire(1)
+            filter2d_line(
+                elems_in_pre[0],
+                elems_in_pre[0],
+                elems_in_pre[1],
+                elem_pre_out,
+                line_width,
+                filter_kernel,
+            )
+            of_out.release(1)
+
+            # Steady-state
+            for _ in range_(1, height_minus_1):
+                elems_in = of_in.acquire(3)
+                elem_out = of_out.acquire(1)
+                filter2d_line(
+                    elems_in[0],
+                    elems_in[1],
+                    elems_in[2],
+                    elem_out,
+                    line_width,
+                    filter_kernel,
+                )
+                of_in.release(1)
+                of_out.release(1)
+
+            # Bottom border
+            elems_in_post = of_in.acquire(2)
+            elem_post_out = of_out.acquire(1)
+            filter2d_line(
+                elems_in_post[0],
+                elems_in_post[1],
+                elems_in_post[1],
+                elem_post_out,
+                line_width,
+                filter_kernel,
+            )
+            of_in.release(2)
+            of_out.release(1)
+
+    workers.append(
+        Worker(
+            filter_fn,
+            [
+                of_intermediates[0].cons(),
+                of_intermediates[1].prod(),
+                filter_kernel_buff,
+                filter2d_line_kernel,
+            ],
+            while_true=False,
+        )
+    )
+
+    def gray2rgba_add_weight_fn(
+        of_in,
+        of_in2,
+        of_out_self,
+        of_in_self,
+        of_out,
+        gray2rgba_line,
+        add_weighted_line,
+    ):
+        elem_in = of_in.acquire(1)
+        elem_out = of_out_self.acquire(1)
+        gray2rgba_line(elem_in, elem_out, line_width)
+        of_in.release(1)
+        of_out_self.release(1)
+
+        elem_in1 = of_in_self.acquire(1)
+        elem_in2 = of_in2.acquire(1)
+        elem_out2 = of_out.acquire(1)
+
+        alpha, beta, gamma = 16384, 0, 0
+        add_weighted_line(
+            elem_in1,
+            elem_in2,
+            elem_out2,
+            line_width_in_bytes,
+            alpha,
+            beta,
+            gamma,
+        )
+        of_in_self.release(1)
+        of_in2.release(1)
+        of_out.release(1)
+
+    workers.append(
+        Worker(
+            gray2rgba_add_weight_fn,
+            [
+                of_intermediates[1].cons(),
+                in_of_l2l1.cons(),
+                of_local.prod(),
+                of_local.cons(),
+                out_of_l1l2.prod(),
+                gray2rgba_line_kernel,
+                add_weighted_line_kernel,
+            ],
+        )
+    )
+
+    tensor_size = width * height * 4
+    tensor_ty = np.ndarray[(tensor_size,), np.dtype[np.int8]]
+    tensor_16x16_ty = np.ndarray[(16, 16), np.dtype[np.int32]]
+
+    rt = Runtime()
+    with rt.sequence(tensor_ty, tensor_16x16_ty, tensor_ty) as (i_in, _b, o_out):
+        rt.start(*workers)
+        rt.fill(in_of_l3l2.prod(), i_in)
+        rt.drain(out_of_l2l3.cons(), o_out, wait=True)
+
+    return Program(iron.get_current_device(), rt).resolve_program()
+
+
+def _make_argparser():
+    p = argparse.ArgumentParser(prog="AIE Edge Detect")
+    add_compile_args(p)
+    p.add_argument("-W", "--width", type=int, default=1920)
+    p.add_argument("-H", "--height", type=int, default=1080)
+    return p
+
+
+def _compile_kwargs(opts):
+    return dict(width=opts.width, height=opts.height)
+
+
+def _rgba2gray_ref(rgba_uint8, height, width):
+    """Numpy port of ``rgba2gray_aie`` (SRS_SHIFT=15)."""
+    rgba = rgba_uint8.reshape(height, width, 4)
+    r = rgba[..., 0].astype(np.int32)
+    g = rgba[..., 1].astype(np.int32)
+    b = rgba[..., 2].astype(np.int32)
+    wt_r = int(round(0.299 * (1 << 15)))  # 9798
+    wt_g = int(round(0.587 * (1 << 15)))  # 19235
+    wt_b = int(round(0.114 * (1 << 15)))  # 3736
+    y = (wt_r * r + wt_g * g + wt_b * b + (1 << 14)) >> 15
+    return np.clip(y, 0, 255).astype(np.uint8)
+
+
+def _filter2d_cv_ref(gray_uint8, height, width):
+    """Numpy equivalent of cv::filter2D with the unscaled Laplacian
+    ``[[0,1,0],[1,-4,1],[0,1,0]]`` + BORDER_REPLICATE."""
+    img = gray_uint8.reshape(height, width).astype(np.float32)
+    padded = np.pad(img, 1, mode="edge")
+    out = (
+        -4.0 * padded[1:-1, 1:-1]
+        + padded[:-2, 1:-1]
+        + padded[2:, 1:-1]
+        + padded[1:-1, :-2]
+        + padded[1:-1, 2:]
+    )
+    return np.clip(out, 0, 255).astype(np.uint8)
+
+
+def _threshold_binary_ref(arr_uint8, thresh, max_val):
+    """cv::threshold with THRESH_BINARY: out = (in > thresh) ? max : 0."""
+    return np.where(arr_uint8 > thresh, np.uint8(max_val), np.uint8(0))
+
+
+def _gray2rgba_ref(gray_uint8):
+    """Replicate gray to R/G/B with alpha=255 (matches ``gray2rgba_aie``)."""
+    flat = gray_uint8.reshape(-1)
+    out = np.zeros((flat.size, 4), dtype=np.uint8)
+    out[:, 0] = flat
+    out[:, 1] = flat
+    out[:, 2] = flat
+    out[:, 3] = 255
+    return out.reshape(-1)
+
+
+def _add_weighted_cv_ref(a_uint8, b_uint8, alpha, beta, gamma):
+    """Numpy equivalent of cv::addWeighted: ``saturate(alpha*a + beta*b + gamma)``.
+    test.cpp passes alpha=beta=1.0, gamma=0.0; the AIE kernel computes
+    ``(a+b)/2`` in fixed-point — the diffs land under ``_EPSILON``.
+    """
+    tmp = a_uint8.astype(np.int32) * alpha + b_uint8.astype(np.int32) * beta + gamma
+    return np.clip(tmp, 0, 255).astype(np.uint8)
+
+
+def _edge_detect_ref(rgba_uint8, height, width):
+    """End-to-end reference mirroring test.cpp's edgeDetect() OpenCV pipeline."""
+    gray = _rgba2gray_ref(rgba_uint8, height, width)
+    edges = _filter2d_cv_ref(gray, height, width)
+    thresholded = _threshold_binary_ref(edges, 10, 255)
+    mask_rgba = _gray2rgba_ref(thresholded)
+    return _add_weighted_cv_ref(rgba_uint8, mask_rgba, 1, 1, 0)
+
+
+# Matches the C++ test.cpp's ``epsilon = 2.0`` tolerance on
+# ``error_per_pixel = sum(abs(actual - golden)) / num_pixels``.
+_EPSILON = 2.0
+
+
+def _run_and_verify(opts):
+    tensor_size = opts.width * opts.height * 4
+    rng = np.random.default_rng(0)
+    in_np = rng.integers(-128, 127, size=(tensor_size,), dtype=np.int8)
+    in_t = iron.tensor(in_np, dtype=np.int8, device="npu")
+    b_t = iron.zeros(16 * 16, dtype=np.int32, device="npu")
+    out_t = iron.zeros(tensor_size, dtype=np.int8, device="npu")
+
+    edge_detect(in_t, b_t, out_t, **_compile_kwargs(opts))
+
+    in_uint8 = in_np.view(np.uint8)
+    expected_uint8 = _edge_detect_ref(in_uint8, opts.height, opts.width)
+    actual = out_t.numpy().view(np.uint8)
+
+    n_diff = int(np.sum(actual != expected_uint8))
+    error_per_pixel = float(
+        np.sum(np.abs(actual.astype(np.int32) - expected_uint8.astype(np.int32)))
+    ) / (opts.width * opts.height)
+    print(f"Number of differences: {n_diff}, average L1 error: {error_per_pixel:.6f}")
+
+    assert_pass(
+        error_per_pixel < _EPSILON,
+        True,
+        fail_msg=f"error_per_pixel {error_per_pixel:.6f} >= epsilon {_EPSILON}",
+    )
+
+
+def main():
+    opts = _make_argparser().parse_args()
+    run_design_cli(
+        edge_detect,
+        opts,
+        compile_kwargs=_compile_kwargs,
+        run_and_verify=_run_and_verify,
+        device=device_from_args,
+    )
+
+
+if __name__ == "__main__":
+    main()

camera/blur_plane.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Scott Boudreaux / Elyan Labs. Commercial license: see ../COMMERCIAL.md
+#
+# Purpose-built NPU blur kernel: a CLEAN single-channel 3x3 Gaussian filter2d on the AIE.
+# No rgba2gray round-trip, no add_weighted overlay (the speckle + 2x-gain sources). The host
+# feeds each color channel as a uint8 plane (multi-pass = re-feed) and recombines -> clean color blur.
+#
+# Dataflow FIX 2026-06-24: the filter's 3-line stencil consumes a WORKER-PRODUCED line stream
+# (a passthrough copy producer), exactly like edge_detect's verified rgba2gray->filter structure —
+# NOT a raw DMA forward (which caused value-dependent gain + line streaks).
+#
+# Unity gain: int16 coeffs >>8 -> int8 [[1,2,1],[2,4,2],[1,2,1]] (sum 16); filter2d stores
+# acc >> (SRS_SHIFT-8 = 4) = acc/16 = exact weighted mean.
+
+import sys, os
+#
+# DEFINITIVE DIAGNOSIS 2026-06-24: with the correct (worker-produced) dataflow AND unity-gain coeffs,
+# the stock kernels.filter2d STILL produces value-dependent output that SATURATES bright pixels to the
+# int8-positive range: uniform 100->100 but 200->132, 255->150. The kernel's accumulation/store path
+# is built for the Laplacian (zero-centered edge outputs) and clamps a unity-sum blur of bright images.
+# This is NOT a dataflow or coeff bug (both fixed). CONCLUSION: a clean NPU blur needs a CUSTOM AIE
+# blur kernel (.cc, hand-written vector intrinsics with a proper uint8 saturate-store), not filter2d.
+# Until then the kit's background blur uses the clean CPU Gaussian (camera/README).
+import numpy as np
+import aie.iron as iron
+from aie.iron import Buffer, CompileTime, In, ObjectFifo, Out, Program, Runtime, Worker, kernels
+from aie.iron.controlflow import range_
+from aie.iron.kernels._common import _make_extern
+
+
+@iron.jit(aiecc_flags=["--alloc-scheme=basic-sequential"])
+def blur_plane(
+    in_tensor: In,
+    out_tensor: Out,
+    *,
+    width: CompileTime[int] = 1280,
+    height: CompileTime[int] = 720,
+):
+    height_minus_1 = height - 1
+    line_width = width
+    line_ty = np.ndarray[(line_width,), np.dtype[np.uint8]]
+
+    pass_through_line = kernels.passthrough(tile_size=line_width, dtype=np.uint8)
+    _kernel_ty = np.ndarray[(3, 3), np.dtype[np.int16]]
+    _blur_src = os.path.join(os.path.dirname(os.path.abspath(__file__)), "kernels", "blur3x3.cc")
+    filter2d_line_kernel = _make_extern(
+        "blurLine", _blur_src,
+        [line_ty, line_ty, line_ty, line_ty, np.int32, _kernel_ty],
+    )
+    # unity-gain Gaussian (>>8 -> int8 [1,2,1;2,4,2;1,2,1], sum 16; filter2d >>4 = /16)
+    filter_kernel_buff = Buffer(
+        np.ndarray[(3, 3), np.dtype[np.int16]],
+        name="kernel",
+        initial_value=np.array(
+            [[256, 512, 256], [512, 1024, 512], [256, 512, 256]], dtype=np.int16
+        ),
+    )
+
+    of_in = ObjectFifo(line_ty, name="in")                       # DMA input
+    of_lines = ObjectFifo(line_ty, depth=4, name="lines")        # worker-produced line stream (filter input)
+    of_out = ObjectFifo(line_ty, name="out")                     # DMA output
+
+    workers = []
+
+    # producer: copy DMA input lines into of_lines, one per call (IRON auto-iterates over height)
+    def copy_fn(of_i, of_o, k):
+        ein = of_i.acquire(1)
+        eout = of_o.acquire(1)
+        k(ein, eout, line_width)
+        of_i.release(1)
+        of_o.release(1)
+
+    workers.append(Worker(copy_fn, [of_in.cons(), of_lines.prod(), pass_through_line]))
+
+    # filter: 3-line stencil over the produced line stream
+    def filter_fn(of_i, of_o, kernel, f2d):
+        for _ in range_(sys.maxsize):
+            ein = of_i.acquire(2)                                # top border: dup first row
+            eout = of_o.acquire(1)
+            f2d(ein[0], ein[0], ein[1], eout, line_width, kernel)
+            of_o.release(1)
+            for _ in range_(1, height_minus_1):                  # steady (i-1, i, i+1)
+                ein = of_i.acquire(3)
+                eout = of_o.acquire(1)
+                f2d(ein[0], ein[1], ein[2], eout, line_width, kernel)
+                of_i.release(1)
+                of_o.release(1)
+            ein = of_i.acquire(2)                                # bottom border: dup last row
+            eout = of_o.acquire(1)
+            f2d(ein[0], ein[1], ein[1], eout, line_width, kernel)
+            of_i.release(2)
+            of_o.release(1)
+
+    workers.append(
+        Worker(filter_fn, [of_lines.cons(), of_out.prod(), filter_kernel_buff, filter2d_line_kernel],
+               while_true=False)
+    )
+
+    plane_ty = np.ndarray[(width * height,), np.dtype[np.uint8]]
+    rt = Runtime()
+    with rt.sequence(plane_ty, plane_ty) as (i_in, o_out):
+        rt.start(*workers)
+        rt.fill(of_in.prod(), i_in)
+        rt.drain(of_out.cons(), o_out, wait=True)
+
+    return Program(iron.get_current_device(), rt).resolve_program()

camera/kernels/blur3x3.cc

@@ -0,0 +1,74 @@
+//===- blur3x3.cc -------------------------------------------------*- C++ -*-===//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Scott Boudreaux / Elyan Labs. Commercial license: see ../../COMMERCIAL.md
+//
+// Custom AIE2 3x3 blur kernel for the XDNA NPU. Unlike mlir-aie's stock filter2d (whose VECTOR
+// path truncates the int16 kernel to int8 via >>8 and saturates bright unity-gain outputs to the
+// int8-positive range — fine for the zero-centered Laplacian, broken for a blur), this uses an
+// int32 accumulator with the int16 kernel directly, >>SRS_SHIFT, and a proper [0,255] uint8 clamp.
+// For a unity-sum kernel (e.g. Gaussian [[256,512,256],[512,1024,512],[256,512,256]] summing 4096):
+// uniform N -> N*4096 >> 12 = N. Exact unity gain, correctly saturated.
+//
+// Symbol: blurLine(l0,l1,l2,out,width,kernel) — same ABI as filter2d's filter2dLine, so it drops
+// into the same 3-line-stencil worker. (Scalar path: correctness over peak throughput; the camera
+// pipeline has large FPS headroom.)
+
+#define NOCPP
+#include <stdint.h>
+#include <aie_api/aie.hpp>
+
+const int32_t SRS_SHIFT = 12;
+
+static inline void blur3x3_scalar(uint8_t *lineIn0, uint8_t *lineIn1,
+                                  uint8_t *lineIn2, uint8_t *output,
+                                  const int32_t width, int16_t *kernel) {
+  int32_t acc;
+
+  // left column: border extension by replicating column 0
+  acc = 0;
+  acc += ((int32_t)lineIn0[0]) * kernel[0 * 3 + 0];
+  acc += ((int32_t)lineIn1[0]) * kernel[1 * 3 + 0];
+  acc += ((int32_t)lineIn2[0]) * kernel[2 * 3 + 0];
+  for (int ki = 1; ki < 3; ki++) {
+    acc += ((int32_t)lineIn0[0 + ki - 1]) * kernel[0 * 3 + ki];
+    acc += ((int32_t)lineIn1[0 + ki - 1]) * kernel[1 * 3 + ki];
+    acc += ((int32_t)lineIn2[0 + ki - 1]) * kernel[2 * 3 + ki];
+  }
+  acc = ((acc + (1 << (SRS_SHIFT - 1))) >> SRS_SHIFT);
+  acc = (acc > UINT8_MAX) ? UINT8_MAX : (acc < 0) ? 0 : acc;
+  output[0] = (uint8_t)acc;
+
+  // interior
+  for (int i = 1; i < width - 1; i++) {
+    acc = 0;
+    for (int ki = 0; ki < 3; ki++) {
+      acc += ((int32_t)lineIn0[i + ki - 1]) * kernel[0 * 3 + ki];
+      acc += ((int32_t)lineIn1[i + ki - 1]) * kernel[1 * 3 + ki];
+      acc += ((int32_t)lineIn2[i + ki - 1]) * kernel[2 * 3 + ki];
+    }
+    acc = ((acc + (1 << (SRS_SHIFT - 1))) >> SRS_SHIFT);
+    acc = (acc > UINT8_MAX) ? UINT8_MAX : (acc < 0) ? 0 : acc;
+    output[i] = (uint8_t)acc;
+  }
+
+  // right column: border extension by replicating last column
+  acc = 0;
+  for (int ki = 0; ki < 2; ki++) {
+    acc += ((int32_t)lineIn0[width + ki - 2]) * kernel[0 * 3 + ki];
+    acc += ((int32_t)lineIn1[width + ki - 2]) * kernel[1 * 3 + ki];
+    acc += ((int32_t)lineIn2[width + ki - 2]) * kernel[2 * 3 + ki];
+  }
+  acc += ((int32_t)lineIn0[width - 1]) * kernel[0 * 3 + 2];
+  acc += ((int32_t)lineIn1[width - 1]) * kernel[1 * 3 + 2];
+  acc += ((int32_t)lineIn2[width - 1]) * kernel[2 * 3 + 2];
+  acc = ((acc + (1 << (SRS_SHIFT - 1))) >> SRS_SHIFT);
+  acc = (acc > UINT8_MAX) ? UINT8_MAX : (acc < 0) ? 0 : acc;
+  output[width - 1] = (uint8_t)acc;
+}
+
+extern "C" {
+void blurLine(uint8_t *lineIn0, uint8_t *lineIn1, uint8_t *lineIn2,
+              uint8_t *out, int32_t lineWidth, int16_t *blurKernel) {
+  blur3x3_scalar(lineIn0, lineIn1, lineIn2, out, lineWidth, blurKernel);
+}
+} // extern "C"

camera/npu_background_blur.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Scott Boudreaux / Elyan Labs. Commercial license: see ../COMMERCIAL.md
+#
+# open-xdna / npu-linux-kit :: background blur — the marquee Studio-Effects feature.
+#
+#   (1) COLOR blur   — the grayscale blur design is run PER CHANNEL (R/G/B), recombined → color blur.
+#   (2) MULTI-PASS   — each channel is blurred N times for strong bokeh (449 FPS/pass → headroom).
+#   (3) SEGMENTATION — a person/background mask composites sharp-foreground + NPU-blurred-background.
+#       Mask source: MediaPipe Selfie (if installed) → ONNX via opencv-DNN (if a model is given) →
+#       a center-ellipse PLACEHOLDER (honest fallback; not real segmentation). A seg model running
+#       ON the NPU is the future drop-in — the blur engine is already proven on-NPU.
+#
+# Honesty (v1): blur defaults to a clean CPU Gaussian; the NPU blur path (--npu-blur) is
+# EXPERIMENTAL (fixed-point quality WIP). Segmentation runs on the CPU. The proven NPU effect is
+# the edge-stylize in npu_camera_daemon.py; a clean on-NPU blur + on-NPU seg are the next builds.
+
+import os, sys, time, argparse
+_NPU_SCALE = 4
+import numpy as np, cv2
+
+MLIR_AIE = os.environ.get("MLIR_AIE_DIR", os.path.expanduser("~/open-xdna/mlir-aie"))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import aie.iron as iron
+from blur_plane import blur_plane                    # custom clean NPU 3x3 blur kernel (blur3x3.cc)
+
+
+_plane_in = _plane_out = _plane_n = None
+def _blur_planes_npu(img, w, h, passes):
+    """Blur each color channel (uint8 plane) with the custom blur3x3 NPU kernel, N passes."""
+    global _plane_in, _plane_out, _plane_n
+    if _plane_n != w * h:
+        _plane_in = iron.tensor(np.zeros(w * h, np.uint8), dtype=np.uint8, device="npu")
+        _plane_out = iron.zeros(w * h, dtype=np.uint8, device="npu")
+        _plane_n = w * h
+    out = img.copy()
+    for c in range(3):
+        ch = np.ascontiguousarray(out[:, :, c])
+        for _ in range(passes):
+            _plane_in.numpy()[:] = ch.reshape(-1)
+            blur_plane(_plane_in, _plane_out, width=w, height=h)
+            ch = _plane_out.numpy().reshape(h, w).copy()
+        out[:, :, c] = ch
+    return out
+
+def npu_color_blur(bgr, W, H, passes=1, scale=4):
+    """Clean color blur on the NPU. Real-time path: blur at reduced resolution (scale) then upscale —
+    background bokeh is low-frequency, so a downscaled blur is visually ~identical and ~scale^2 faster.
+    The blur itself is bit-clean (custom blur3x3 kernel: no rgba2gray round-trip, no speckle)."""
+    if scale > 1:
+        w2 = max(64, ((W // scale) // 64) * 64)   # width must be a multiple of 64 (AIE granularity)
+        h2 = max(2, ((H // scale) // 2) * 2)       # even height
+        small = cv2.resize(bgr, (w2, h2), interpolation=cv2.INTER_AREA)
+        sb = _blur_planes_npu(small, w2, h2, passes)
+        return cv2.resize(sb, (W, H), interpolation=cv2.INTER_LINEAR)
+    return _blur_planes_npu(bgr, W, H, passes)
+
+
+_mask_cache = {"m": None, "i": -1, "every": 3}
+def get_mask(bgr, W, H, seg):
+    """Person mask (1=foreground). Recomputed every Nth frame and reused between (people move slowly)."""
+    _mask_cache["i"] += 1
+    if _mask_cache["m"] is not None and seg[0] != "placeholder" and (_mask_cache["i"] % _mask_cache["every"]):
+        return _mask_cache["m"]
+    kind, obj = seg
+    if kind == "mediapipe":
+        res = obj.process(cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB))
+        m = (res.segmentation_mask > 0.5).astype(np.uint8)
+        return cv2.resize(m, (W, H), interpolation=cv2.INTER_NEAREST)
+    if kind == "onnx":                               # onnxruntime session (MODNet-style matte)
+        inp = cv2.resize(cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB), (256, 256)).astype(np.float32)
+        inp = ((inp / 255.0 - 0.5) / 0.5).transpose(2, 0, 1)[None]   # [-1,1], NCHW RGB
+        out = obj.run(None, {obj.get_inputs()[0].name: inp})[0]
+        m = (cv2.resize(out[0, 0], (W, H)) > 0.5).astype(np.uint8); _mask_cache["m"] = m; return m
+    # placeholder: center ellipse (NOT real segmentation — demo stub)
+    m = np.zeros((H, W), np.uint8)
+    cv2.ellipse(m, (W // 2, H // 2), (W // 5, int(H * 0.45)), 0, 0, 360, 1, -1)
+    return m
+
+
+def load_seg(onnx_path=None):
+    try:
+        import mediapipe as mp
+        return ("mediapipe", mp.solutions.selfie_segmentation.SelfieSegmentation(model_selection=1))
+    except Exception:
+        pass
+    if onnx_path and os.path.exists(onnx_path):
+        try:
+            import onnxruntime as ort
+            return ("onnx", ort.InferenceSession(onnx_path, providers=["CPUExecutionProvider"]))
+        except Exception as e:
+            print(f"  [seg] onnxruntime load failed: {e}")
+    print("  [seg] no mediapipe/onnx — using CENTER-ELLIPSE PLACEHOLDER (not real segmentation)")
+    return ("placeholder", None)
+
+
+def background_blur(bgr, W, H, in_t, b_t, out_t, seg, passes, npu_blur=False):
+    mask = get_mask(bgr, W, H, seg)                          # CPU segmentation
+    if npu_blur:
+        # EXPERIMENTAL: NPU color multi-pass blur. Known quality issues (fixed-point: the
+        # filter2d int16->int8 coeff truncation + multi-pass gain compounding → artifacts /
+        # saturation). Needs a purpose-built unity-gain NPU blur kernel. Not production-ready.
+        blurred = npu_color_blur(bgr, W, H, passes, _NPU_SCALE)
+    else:
+        # Default: strong CPU Gaussian (clean bokeh). The NPU's proven role here is the edge
+        # effect; a clean NPU blur is WIP (see npu_blur above).
+        blurred = cv2.GaussianBlur(bgr, (0, 0), sigmaX=8 + 2 * passes)
+    m3 = cv2.GaussianBlur(mask.astype(np.float32), (7, 7), 0)[:, :, None]   # feather mask edges
+    return (bgr * m3 + blurred * (1 - m3)).astype(np.uint8)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--device", default="/dev/video0")
+    ap.add_argument("-W", "--width", type=int, default=1280)
+    ap.add_argument("-H", "--height", type=int, default=720)
+    ap.add_argument("--passes", type=int, default=4, help="blur strength")
+    ap.add_argument("--npu-blur", action="store_true", help="blur on the NPU (custom kernel); default = CPU Gaussian")
+    ap.add_argument("--npu-scale", type=int, default=4, help="NPU blur downscale factor (4 = validated/known-good; >4 can ERT-timeout, AIE dim-sensitive)")
+    ap.add_argument("--onnx", default=None, help="optional segmentation ONNX model for opencv-DNN")
+    ap.add_argument("--loopback", default=None)
+    ap.add_argument("--frames", type=int, default=60)
+    ap.add_argument("--image", default=None, help="blur a still image instead of the camera (test)")
+    opts = ap.parse_args()
+    W, H = opts.width, opts.height
+    global _NPU_SCALE; _NPU_SCALE = opts.npu_scale
+    seg = load_seg(opts.onnx)
+    ts = W * H * 4
+    in_t = iron.tensor(np.zeros(ts, np.int8), dtype=np.int8, device="npu")
+    b_t = iron.zeros(16 * 16, dtype=np.int32, device="npu")
+    out_t = iron.zeros(ts, dtype=np.int8, device="npu")
+
+    if opts.image:                                           # still-image test path
+        img = cv2.resize(cv2.imread(opts.image), (W, H))
+        background_blur(img, W, H, in_t, b_t, out_t, seg, opts.passes, opts.npu_blur)  # warm
+        t0 = time.perf_counter(); res = background_blur(img, W, H, in_t, b_t, out_t, seg, opts.passes, opts.npu_blur)
+        dt = time.perf_counter() - t0
+        cv2.imwrite("./bgblur_before.png", img); cv2.imwrite("./bgblur_after.png", res)
+        print(f"  background-blur still: {dt*1e3:.1f} ms ({opts.passes} passes/ch, seg={seg[0]}) -> saved bgblur_*.png")
+        return
+
+    cap = cv2.VideoCapture(opts.device, cv2.CAP_V4L2)
+    cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*"MJPG"))
+    cap.set(cv2.CAP_PROP_FRAME_WIDTH, W); cap.set(cv2.CAP_PROP_FRAME_HEIGHT, H)
+    ok, f = cap.read()
+    if not ok: print("ERROR: no camera frame"); sys.exit(1)
+    f = cv2.resize(f, (W, H)); background_blur(f, W, H, in_t, b_t, out_t, seg, opts.passes, opts.npu_blur)  # warm
+    n = 0; t0 = time.perf_counter()
+    sink = None
+    if opts.loopback:
+        import pyvirtualcam
+        sink = pyvirtualcam.Camera(width=W, height=H, fps=30, device=opts.loopback,
+                                   fmt=pyvirtualcam.PixelFormat.RGB)
+    while n < opts.frames or (opts.loopback and opts.frames == 0):
+        ok, f = cap.read()
+        if not ok: break
+        if f.shape[1] != W or f.shape[0] != H: f = cv2.resize(f, (W, H))
+        res = background_blur(f, W, H, in_t, b_t, out_t, seg, opts.passes, opts.npu_blur)
+        if sink: sink.send(cv2.cvtColor(res, cv2.COLOR_BGR2RGB)); sink.sleep_until_next_frame()
+        n += 1
+    dt = time.perf_counter() - t0; cap.release()
+    if sink: sink.close()
+    print(f"  background-blur live: {n} frames, {n/dt:.1f} FPS end-to-end "
+          f"({opts.passes} strength, seg={seg[0]}, blur={'NPU-exp' if opts.npu_blur else 'CPU'})")
+
+
+if __name__ == "__main__":
+    main()

camera/npu_camera_daemon.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Scott Boudreaux / Elyan Labs. Commercial license: see ../COMMERCIAL.md
+#
+# open-xdna :: NPU camera-effects daemon (A1) — core path.
+# Captures real frames from a v4l2 camera, runs the per-frame conv/colorspace effect on the
+# XDNA1 NPU (rgba2gray -> 3x3 filter2d -> threshold -> gray2rgba -> blend = edge-stylize), and
+# measures LIVE end-to-end FPS on real camera data. Saves a before/after sample as proof.
+#
+# This is the core of an open-source Linux "Studio Effects"-style NPU webcam filter. The virtual
+# v4l2loopback output (so Zoom/OBS see it as a camera) is the next layer; --loopback enables it
+# if /dev/videoN (v4l2loopback) + pyvirtualcam are present.
+
+import os, sys, time, argparse
+import numpy as np
+import cv2
+
+MLIR_AIE = os.environ.get("MLIR_AIE_DIR", os.path.expanduser("~/open-xdna/mlir-aie"))
+sys.path.insert(0, os.path.join(MLIR_AIE, "programming_examples/vision/edge_detect"))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))   # for blur_pipeline (same dir)
+import aie.iron as iron
+_DESIGN = None                               # @iron.jit per-frame pipeline; set in main() from --effect
+
+
+def npu_effect(frame_bgr, W, H, in_t, b_t, out_t):
+    """One frame: BGR uint8 -> NPU effect -> BGR uint8."""
+    rgba = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGBA).reshape(-1)          # H*W*4 uint8
+    in_t.numpy()[:] = rgba.view(np.int8)                                    # in-place into NPU tensor
+    _DESIGN(in_t, b_t, out_t, width=W, height=H)
+    out_rgba = out_t.numpy().view(np.uint8).reshape(H, W, 4)
+    return cv2.cvtColor(out_rgba, cv2.COLOR_RGBA2BGR)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--device", default="/dev/video0")
+    ap.add_argument("-W", "--width", type=int, default=1280)
+    ap.add_argument("-H", "--height", type=int, default=720)
+    ap.add_argument("--frames", type=int, default=120)
+    ap.add_argument("--loopback", default=None, help="v4l2loopback device to output to, e.g. /dev/video10")
+    ap.add_argument("--stream-frames", type=int, default=0, help="frames to stream (0 = until Ctrl-C)")
+    ap.add_argument("--effect", choices=["edge", "blur"], default="edge", help="NPU effect")
+    ap.add_argument("--out", default="./cam_sample")
+    opts = ap.parse_args()
+    W, H = opts.width, opts.height
+
+    global _DESIGN
+    if opts.effect == "blur":
+        from blur_pipeline import blur as _DESIGN
+    else:
+        from edge_detect import edge_detect as _DESIGN
+
+    cap = cv2.VideoCapture(opts.device, cv2.CAP_V4L2)
+    cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*"MJPG"))   # MJPG → higher USB capture FPS
+    cap.set(cv2.CAP_PROP_FRAME_WIDTH, W); cap.set(cv2.CAP_PROP_FRAME_HEIGHT, H)
+    if not cap.isOpened():
+        print(f"ERROR: cannot open {opts.device}"); sys.exit(1)
+
+    ts = W * H * 4
+    in_t = iron.tensor(np.zeros(ts, dtype=np.int8), dtype=np.int8, device="npu")
+    b_t = iron.zeros(16 * 16, dtype=np.int32, device="npu")
+    out_t = iron.zeros(ts, dtype=np.int8, device="npu")
+
+    print(f"open-xdna :: NPU camera daemon — {opts.device} @ {W}x{H}, {opts.frames} frames")
+    # warm: grab one frame, compile the pipeline
+    ok, f = cap.read()
+    if not ok: print("ERROR: no frame from camera"); sys.exit(1)
+    f = cv2.resize(f, (W, H))
+    npu_effect(f, W, H, in_t, b_t, out_t)
+    cv2.imwrite(opts.out + "_before.png", f)
+    cv2.imwrite(opts.out + "_after.png", npu_effect(f, W, H, in_t, b_t, out_t))
+
+    # Stream mode: capture -> NPU effect -> v4l2loopback virtual cam (so Zoom/OBS/browser see it)
+    if opts.loopback:
+        import pyvirtualcam
+        nf = opts.stream_frames
+        print(f"  streaming NPU-effected frames -> {opts.loopback}"
+              + (f" for {nf} frames" if nf else " (Ctrl-C to stop)"))
+        i = 0
+        with pyvirtualcam.Camera(width=W, height=H, fps=30, device=opts.loopback,
+                                 fmt=pyvirtualcam.PixelFormat.RGB) as vcam:
+            while nf == 0 or i < nf:
+                ok, f = cap.read()
+                if not ok: break
+                if f.shape[1] != W or f.shape[0] != H: f = cv2.resize(f, (W, H))
+                out_bgr = npu_effect(f, W, H, in_t, b_t, out_t)
+                vcam.send(cv2.cvtColor(out_bgr, cv2.COLOR_BGR2RGB))
+                vcam.sleep_until_next_frame()
+                i += 1
+        cap.release()
+        print(f"  streamed {i} frames to {opts.loopback} — select 'NPU Camera (open-xdna)' in any app.")
+        return
+
+    # A) capture-only (find the camera ceiling)
+    n = 0; t0 = time.perf_counter()
+    while n < opts.frames:
+        ok, f = cap.read()
+        if not ok: break
+        if f.shape[1] != W or f.shape[0] != H: f = cv2.resize(f, (W, H))
+        n += 1
+    cap_fps = n / (time.perf_counter() - t0)
+
+    # B) capture + NPU effect (end-to-end)
+    n = 0; t0 = time.perf_counter()
+    while n < opts.frames:
+        ok, f = cap.read()
+        if not ok: break
+        if f.shape[1] != W or f.shape[0] != H: f = cv2.resize(f, (W, H))
+        npu_effect(f, W, H, in_t, b_t, out_t)
+        n += 1
+    e2e_fps = n / (time.perf_counter() - t0)
+    cap.release()
+
+    npu_only = 1000.0 / 2.21 if (W, H) == (1280, 720) else None   # from npu_camera_fps.py
+    print(f"  capture-only:        {cap_fps:5.1f} FPS  (camera/USB ceiling)")
+    print(f"  capture + NPU effect:{e2e_fps:5.1f} FPS  (end-to-end)")
+    if npu_only: print(f"  NPU effect alone:    {npu_only:5.0f} FPS  (2.21 ms/frame @720p — not the bottleneck)")
+    print(f"  sample saved: {opts.out}_before.png / _after.png")
+    overhead = (1.0/e2e_fps - 1.0/cap_fps) * 1000 if e2e_fps > 0 and cap_fps > 0 else 0
+    print(f"  VERDICT: NPU adds ~{overhead:.1f} ms/frame; the limit is CAMERA CAPTURE ({cap_fps:.0f} FPS), not the NPU.")
+
+
+if __name__ == "__main__":
+    main()

camera/npu_camera_fps.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Scott Boudreaux / Elyan Labs. Commercial license: see ../COMMERCIAL.md
+#
+# open-xdna :: FPS gate for an NPU camera-effects daemon (A1).
+# Times the full per-frame conv/colorspace pipeline (rgba2gray -> 3x3 filter2d -> threshold ->
+# gray2rgba -> blend) on the XDNA1 NPU at camera resolutions, INCLUDING the host DMA round-trip
+# (fill input frame -> run -> drain output) — exactly what a v4l2 daemon pays per frame.
+# Gate: >=30 FPS at 720p/1080p means real-time camera effects on the NPU are feasible.
+
+import os, sys, time
+import numpy as np
+
+MLIR_AIE = os.environ.get("MLIR_AIE_DIR", os.path.expanduser("~/open-xdna/mlir-aie"))
+sys.path.insert(0, os.path.join(MLIR_AIE, "programming_examples/vision/edge_detect"))
+import aie.iron as iron
+from edge_detect import edge_detect          # the @iron.jit per-frame vision pipeline
+
+
+def bench(W, H, iters=50):
+    ts = W * H * 4                            # RGBA int8 frame
+    rng = np.random.default_rng(0)
+    in_t = iron.tensor(rng.integers(-128, 127, size=(ts,), dtype=np.int8), dtype=np.int8, device="npu")
+    b_t = iron.zeros(16 * 16, dtype=np.int32, device="npu")
+    out_t = iron.zeros(ts, dtype=np.int8, device="npu")
+    # warm/compile (JIT specializes per W,H)
+    edge_detect(in_t, b_t, out_t, width=W, height=H)
+    edge_detect(in_t, b_t, out_t, width=W, height=H)
+    t0 = time.perf_counter()
+    for _ in range(iters):
+        edge_detect(in_t, b_t, out_t, width=W, height=H)
+    dt = (time.perf_counter() - t0) / iters
+    return dt * 1e3, 1.0 / dt
+
+
+def main():
+    print("open-xdna :: NPU camera-effects FPS gate (full conv/colorspace pipeline + DMA round-trip)")
+    print(f"  {'res':>8} {'pixels':>10} {'ms/frame':>10} {'FPS':>8}   verdict")
+    for W, H, name in [(640, 480, "480p"), (1280, 720, "720p"), (1920, 1080, "1080p")]:
+        ms, fps = bench(W, H)
+        v = "OK ≥60" if fps >= 60 else ("OK ≥30" if fps >= 30 else "below 30 — too slow")
+        print(f"  {name:>8} {W*H:>10} {ms:>10.2f} {fps:>8.1f}   {v}")
+    print("  (per-frame = full pipeline + host fill/drain; this is the daemon's real per-frame cost)")
+
+
+if __name__ == "__main__":
+    main()

camera/test_blur.py

@@ -0,0 +1,32 @@
+import sys, time, os
+import numpy as np, cv2
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+import aie.iron as iron
+from blur_pipeline import blur
+
+W, H = 1280, 720
+ts = W * H * 4
+# sharp checkerboard test pattern — blur must smooth it
+img = np.zeros((H, W, 4), np.uint8); img[:, :, 3] = 255
+mask = (np.add.outer(np.arange(H), np.arange(W))) % 2 == 0
+img[mask] = [255, 255, 255, 255]
+
+in_t = iron.tensor(img.reshape(-1).view(np.int8), dtype=np.int8, device="npu")
+b_t = iron.zeros(16 * 16, dtype=np.int32, device="npu")
+out_t = iron.zeros(ts, dtype=np.int8, device="npu")
+blur(in_t, b_t, out_t, width=W, height=H)
+blur(in_t, b_t, out_t, width=W, height=H)
+t0 = time.perf_counter()
+for _ in range(50):
+    blur(in_t, b_t, out_t, width=W, height=H)
+dt = (time.perf_counter() - t0) / 50
+o = out_t.numpy().view(np.uint8).reshape(H, W, 4)
+
+sharp_var = float(img[H // 2, :, 0].astype(np.float32).var())
+blur_var = float(o[H // 2, :, 0].astype(np.float32).var())
+cv2.imwrite(os.path.join(HERE, "blur_before.png"), cv2.cvtColor(img, cv2.COLOR_RGBA2BGR))
+cv2.imwrite(os.path.join(HERE, "blur_after.png"), cv2.cvtColor(o, cv2.COLOR_RGBA2BGR))
+smoothed = "SMOOTHED ok" if blur_var < sharp_var * 0.8 else "NOT smoothed?"
+print(f"blur @720p: {dt*1e3:.2f} ms/frame -> {1/dt:.0f} FPS")
+print(f"row variance sharp={sharp_var:.0f} -> blurred={blur_var:.0f}  ({smoothed})")

embeddings/README.md

@@ -0,0 +1,6 @@
+# embeddings (planned)
+
+Batch sentence/RAG embedding generation on the NPU. **Status: candidate, not built.**
+Rationale: embeddings are matmul-heavy and *batchable*, so they amortize the NPU's dispatch
+overhead toward its ~64 GFLOP/s peak (measured in open-xdna) and offload the CPU/iGPU at ~6.6 W.
+Needs: an embedding model's matmuls expressed via IRON, + a server interface.

ggml-backend/README.md

@@ -0,0 +1,5 @@
+# ggml-backend (planned — the foundational enabler)
+
+An XDNA NPU backend for ggml/llama.cpp so the NPU can participate in LLM inference directly
+(not just as a coprocessor). **Status: not built — the biggest lift, biggest payoff.** Until then,
+the NPU's measured LLM role is the prune/vision coprocessor (see open-xdna).

reply_to_poizone.txt

@@ -0,0 +1,7 @@
+Thanks — and that's a sharp catch, you're right to push on it. I re-ran it and put it through an independent model review, and the honest answer lands on your side:
+
+It's a real measurement but most likely a software-stack artifact, not a hardware result. Re-test (7B Q4_K, pp512, 780M via llama.cpp Vulkan/RADV): sweeping ubatch 256 → 1024 → 2048 left prefill flat at ~300 t/s, and pp1024 was ~295 — so it's robust, not an under-tuned batch-size knob. But that ~2.6x CPU lead almost certainly reflects the immaturity of the Mesa/RADV Vulkan Q4_K GEMM kernels (tiling / register-blocking / quantized paths) vs llama.cpp's hand-tuned AVX-512 CPU GEMM — not the 780M's hardware ceiling. RDNA3 has the FP16 throughput; the open Vulkan path just isn't realizing it on prefill yet.
+
+So I've narrowed the claim in the repo to: "on the llama.cpp Vulkan/RADV stack, CPU prefill beats the 780M ~2.6x, robust to tuning — a software-stack characteristic, not proven hardware superiority." A ROCm comparison on the same silicon would settle it (no ROCm on my box yet — it's exactly what I'd test on AMD Dev Cloud). Decode still favors the 780M (+38–44%), as expected.
+
+Updated BENCHMARKS.md with the re-test + this caveat, credited to your review. 🙏

requirements.txt

@@ -0,0 +1,7 @@
+# Host-side deps (install into your IRON/mlir-aie venv):
+opencv-python-headless>=4.8
+pyvirtualcam>=0.11
+onnxruntime>=1.16
+numpy>=1.24
+ml_dtypes>=0.3
+# Plus a working XDNA NPU stack (XRT + amd/xdna-driver + IRON/mlir-aie + Peano) — see open-xdna.