相機輸入節點

以下 libcamera 指南說明預設後端。Metoak SIMOR 獨立所有的原始張量請參閱下方 V4L2 章節。

CameraInput 是一個來源節點，用於透過 libcamera 和 GStreamer 的 libcamerasrc 暴露的 MIPI 攝影機。當您希望圖中的影格來自 DevKit 攝影機堆疊，而不是來自 run.push(...) 時，請將其用於由來源擁有的圖的開頭。

如需任務指南，請參閱 使用 MIPI 相機。。

先決條件

在使用 CameraInput 之前，請先在 Neat 之外開啟相機：

• 在 Modalix DevKit 關閉電源時，連接相機。
• 選擇一個與載板、相機廠商、感測器和連接埠相符的 .dtbo 疊加層；
• 確認 libcamera 是否已列出相機。
• 確認 libcamerasrc 是否能夠串流您計畫要求的精確 format,width,height,framerate。

camera_name 是 libcamera 相機的名稱。如果想要使用預設相機，請不要設定此參數；如果板子上有多個相機，請從 cam -l 複製相機名稱。

快速入門

#include <neat.h>

namespace neat = simaai::neat;

neat::CameraInputOptions opt;
opt.width = 1920;
opt.height = 1080;
opt.framerate_num = 30;
opt.framerate_den = 1;
opt.format = "NV12";
opt.buffer_name = "camera0";
opt.allow_cpu_fallback = true;

neat::Graph graph;
graph.add(neat::nodes::CameraInput(opt));
graph.add(neat::nodes::Output("frames"));

neat::Run run = graph.build();
std::optional<neat::Sample> frame = run.pull(/*timeout_ms=*/5000);

由於 CameraInput 擁有原始資料，因此在建立圖時，除非您的應用程式確實有另一個應用程式推送的輸入，否則請勿建立公開的 Input 節點。

API 介面

namespace simaai::neat {
struct CameraInputOptions;
class CameraInput;
}

namespace simaai::neat::nodes {
std::shared_ptr<simaai::neat::Node> CameraInput(
    simaai::neat::CameraInputOptions opt = {});
std::shared_ptr<simaai::neat::Node> CameraInputWithCaptureBuffers(
    simaai::neat::CameraInputOptions opt,
    std::uint32_t capture_buffer_count);
}

Python：

opt = pyneat.CameraInputOptions()
node = pyneat.nodes.camera_input(opt, capture_buffer_count=32)

選項

欄位	預設值	意義
camera_name	未設定	這是 libcamera 相機名稱的選用參數，通常會從 cam -l 複製過來。如果未設定，libcamera 將會選擇預設相機。
width	1920	以像素為單位，指定所需的畫面寬度。必須受到相機模式和疊加層的支援。
height	1080	以像素為單位，指定要求的影格高度。
framerate_num	30	幀率分子。
framerate_den	1	幀率分母。0 已正規化為 1。
format	"NV12"	。已要求使用 video/x-raw 格式。NV12 是建議的模型預處理路徑。
buffer_name	"camera"	邏輯緩衝區名稱，用於後續的中繼資料和模型路徑命名。
insert_queue	true	在設定器協商和零拷貝驗證之後，插入一個小型即時來源佇列。
leaky_queue	true	讓佇列在下游處具有「漏水」特性，這樣即時圖就會優先選擇較新的影格，而不是過時的後備資料。
queue_depth	2	當 insert_queue 為 true 時，佇列中最多可容納的緩衝區數量。
allow_cpu_fallback	false	如果設定為 false，則需要相機/裝置支援零拷貝功能。 僅將其設定為 true，才能選擇使用 Neat 的私有自適應橋接，連接到 SiMaAI 記憶體。

capture_buffer_count 現在也是 CameraInputOptions 欄位。0 保留後端預設值，非零值覆寫擷取緩衝區數量。既有 C++ 工廠與 Python 關鍵字仍可使用。libcamera 上限為 128；原始 V4L2 需要 4–128 個緩衝區。

輸入與輸出合約

合約條款	行為
輸入角色	來源節點。圖形會從相機中提取畫面；應用程式不會將樣本推送至此節點。
輸出媒體類型為	video/x-raw。
輸出格式	要求的 format，通常為 NV12。
記憶體合約	偏好使用裝置/SiMaAI 的零拷貝方式。啟用備援機制後，作業系統/libcamera 緩衝區會被轉換為 SiMaAI 記憶體，以便後續的 CVU/MLA 階段使用。
限制最大支援能力	根據使用者要求的選項，提供靜態提示。在執行階段進行的最大支援能力協商，仍然取決於相機堆疊。

零複製與備援機制

allow_cpu_fallback = false 是預設值，它要求嚴格的相機/設備零拷貝。除非已安裝的 libcamerasrc 公開通用的 external-buffer-mode 屬性，並且記憶體庫可以將相機分配匯出為 DMA-BUF，否則建置將會失敗，並顯示可操作的錯誤。

Neat 始終將其私有相機橋接直接放置在 capsfilter 之後，並在即時佇列之前。該橋接通過 GStreamer 的下游 GST_QUERY_ALLOCATION 提出一個標準池。該池從已驗證的 caps 中獲取平面大小和步長，從一個打包的 SiMaAI 分配中分配它們，並為每個平面匯出一個 DMA-BUF。libcamerasrc 將這些 DMA-BUF 導入到 ISP 捕獲佇列中。該橋接驗證結果，並在嚴格模式下解包相同的打包分配，而無需進行拷貝。

根據下游所有者，將 capture_buffer_count 傳遞給相機工廠。一個時間編碼器或深度非同步 ML 圖可能需要 32 個緩衝區；一個低延遲的 CV 圖可能使用更少的緩衝區並丟棄過時的幀。此設定僅控制 ISP 輸出/應用程式週期。它不會擴大內核的私有 CSI 到 ISP RAW 傳輸環，並且與 GStreamer 的 queue_depth 丟棄策略無關。

明確設定 allow_cpu_fallback = true，以允許已存在的橋接在相機堆疊無法滿足提出的分配器要求時進行拷貝。如果上游提供 SiMaAI/EV74 緩衝區，則橋接會直接傳遞這些緩衝區。否則，它會將相機幀複製到一個池化的 SiMaAI 緩衝區中，並附加下游階段所期望的元資料。該私有拷貝池會按需增長，而不是受到 queue_depth 的限制，這允許下游的「漏」佇列丟棄過時的幀，而無需橋接首先停止。

回退名稱表示橋接可以接受作業系統/libcamera 緩衝區。這並不意味著您應該將調整大小、色彩轉換或正規化移動到 CPU。只要路徑支援，請將這些操作保留在模型管理的 CVU 預處理中。

不要為 CameraInput 添加 OsToSima 節點。適配工作屬於相機源路徑。

常見的圖形

直接擷取相機畫面：

CameraInput -> Output

將相機對準模型：

CameraInput -> model.graph({include_input=false, include_output=true})

對於模型管線，請透過 Model::Options::preprocess 或 pyneat.ModelOptions.preprocess 來設定預處理，以確保調整大小、色彩轉換、正規化、量化和細分等操作都保留在模型管理的 CVU 流程中。

失效模式

錯誤	可能原因
build.plugin_missing	，libcamerasrc 或 neatcamerabridge 缺少於執行階段的外掛程式集中。
misconfig.media_caps / not-negotiated	攝影機不支援您所要求的格式、解析度或幀率。
嚴格的零拷貝錯誤	，allow_cpu_fallback 為「否」，且相機來源未公開 SiMaAI 零拷貝屬性。
讀取逾時	攝影機未傳輸畫面，圖的後壓過大，或攝影機堆疊已停止串流。
綠色、紫色或顏色過於鮮豔的相框。	相框格式或模型的預處理色彩轉換可能出錯，或者相框的顏色已經存在於相機的 ISP/libcamera 輸出中。首先驗證一個 NV12 格式的圖像，看看是否在 Neat 之外也有同樣的問題。

具有獨立記憶體的 raw V4L2 擷取

兩個後端都使用既有的 CameraInput(options)（Python：camera_input）。以下範例選擇僅適用於 Linux 的 Metoak SIMOR 原始複製設定檔。請指定實際擷取裝置；/dev/video1 僅為範例。其他平台會回報不支援的後端錯誤。

#include <neat.h>
namespace n = simaai::neat;

n::CameraInputOptions camera;
camera.device = "/dev/video1";
camera.profile = n::CameraProfile::MetoakSimor;

n::Graph capture;
capture.add(n::nodes::CameraInput(camera));
capture.add(n::nodes::Output());

import pyneat as neat

camera = neat.CameraInputOptions()
camera.device = "/dev/video1"
camera.profile = neat.CameraProfile.MetoakSimor

capture = neat.Graph()
capture.add(neat.nodes.camera_input(camera))
capture.add(neat.nodes.output())

MetoakSimor 在未設定 zero_copy 時預設使用獨立複製擷取。每個出列的 MMAP 影格都會在相機緩衝區重新入列前複製到獨立的池化系統記憶體。明確設定 zero_copy=false 的行為相同；此設定檔不支援 DMA-BUF 匯出/匯入，因此 zero_copy=true 會遭拒絕，不會隱含回退。camera_name 與 allow_cpu_fallback 僅供 libcamera 使用。保留裝置既有頻率；framerate_num/framerate_den 不會設定此設定檔。

輸出是平坦的 UInt8 張量 [bytesused]，包含有效的列填補與尾端資料，而非解碼後的影像。 可從 Sample.caps_string 取得協商後的 fourcc、width、height、row-stride、sizeimage。 解讀裝置通訊協定之前，請勿重塑為解碼影像尺寸或捨棄尾端資料。傳送時間戳記屬於中繼資料， 不包含在張量位元組內。

capture_buffer_count 預設為 8（4–128）、output_buffer_count 為 8（2–128）、 frame_timeout_ms 為 2000（1–60000）。保留的輸出會占用記憶體池槽位。池滿時須釋放輸出才能恢復擷取； 保留的張量絕不會被覆寫。啟用佇列時，queue_depth 必須為正值且小於 output_buffer_count。 停止時會中斷對記憶體池的等待。

開始擷取前，請依 BSP 設定裝置的媒體控制器連結與 pad 格式；Neat 不會改寫媒體圖。請勿同時執行其他擷取用戶端。平台與 USB 裝置使用相同的 V4L2 MMAP 生命週期。驅動程式必須遵守 STREAMOFF 契約：複製模式無法讓有缺陷的核心 DMA 結束處理變安全。結束失敗時必須復原裝置，而非自動重新開啟。

ROS/SIMOR 的 CPU 解包、校正與 ROS 發布仍由應用程式負責。應用程式可將原本的六個輸入 送入另一個處理圖中的 MetoakDepth graph 20。此擷取 API 不加入 SIMOR 處理， 也不需要 graph 21、新韌體或修改現有 ROS 整合。

啟動時會先準備輸出 caps 和 CPU 緩衝區池，再將相機緩衝區排入佇列。停止時會中斷影格與記憶體池等待，結束擷取後再釋放輸出池。已傳送的張量在停止後仍有效。擷取結束錯誤會透過 GStreamer 匯流排回報，並禁止重新啟動該來源；結束程序不能取代裝置復原。

設定檔選擇與相容性

• profile=Default（預設）一律使用 libcamera，並保留 camera_name 選擇。未指定 profile=MetoakSimor 卻提供 device 會遭拒絕，不會隱含選擇 Metoak。
• profile=MetoakSimor 在內部選擇具有獨立複製所有權的 V4L2、RAW8、BA81 與 1920×360 傳輸尺寸。它取代原有 NV12/1080 預設值；其他衝突格式或尺寸會遭拒絕。此設定檔不代表所有 Metoak 相機。
• SIMOR 設定檔未指定 device 時，媒體拓撲中必須恰有一個符合的端點。缺少、模糊或混合感測器路徑都會失敗。探索不會開啟擷取裝置；明確指定設定檔和裝置可略過探索。
• 像素格式不是後端選擇器。一般原始/Bayer 請求仍使用 libcamera 路徑；此變更沒有新增或驗證 Bayer caps 協商。設定檔決定傳輸 FourCC，沒有公開的 FourCC 選項。
• 對 MetoakSimor，未設定的 zero_copy 會解析為 false，明確設定 true 則遭拒絕。對 libcamera，未設定會保留 allow_cpu_fallback；false 允許既有複製回退，true 要求零複製。矛盾的設定會遭拒絕。
• 實作只在節點建立時選擇一次，早於圖的合約傳播。沒有公開的 backend 選項；失敗時不會切換實作。探索不會設定媒體連結或接腳格式。

只有未指定 device 的 MetoakSimor 設定檔會掃描媒體控制器。這些中繼資料查詢是同步核心呼叫，不保證執行時間上限。控制器沒有回應時，請同時設定 device 和 profile=MetoakSimor 以略過探索。

僅使用 CameraInput(options) 與 CameraInputOptions；V4L2 設定為內部實作。manifest 與 SONAME 維持 Core ABI 5。這次尚未發布的整合已改變公開選項與節點配置：請重新建置 C++ 使用端並搭配相符的 Python wheel。不要將舊 ABI-5 二進位檔與新標頭或執行階段混用。