VPP Current · Camera FOV reference

從 Camera 規格到 Floorplan 2D FOV

本頁是 VPP Current 的 canonical reference：每個 Channel 先收斂規格與安裝狀態，再求 Current H/V FOV、地面投影、DORI 外緣與最終 shape。公式與政策只在其所屬章節定義一次。

執行 npm run docs:vpp-ivsd 開啟 VPP Camera FOV pipeline 互動圖。

01

Inputs：產品能力、安裝狀態與畫布

Camera product spec 是型號層級資料；Placement 是某一顆 Camera 的安裝實例；Channel 可覆寫自己的方向與焦距；Floorplan 提供 origin 與 scale。Current FOV 是計算結果，不是另一個型錄欄位。

來源輸入責任
Camera product specfocalLengthMin/Max、H/V FOV、sensorSize、maxResolution、isVariFocal、modelType、channels描述型號的光學範圍與產品分類；focal guard 見 Fallbacks。
PlacementinstallationHeight、tiltAngle、focalLength、rotation、x/y、mount 資訊描述這一顆 Camera 的位置、方向與目前 zoom snapshot。
Channel每個 Channel 的 tilt、focal、rotation各自重跑完整計算並產生一個 2D FOV shape。
Floorplanmpp、origin pixel把 meter footprint 轉為畫布座標；不改變 optical FOV。

Source VPP-FLOW-E1 · VPP-FLOW-E3 · VPP-FLOW-E2

02

Resolved input：每個 Channel 的實際計算參數

同一欄位依 Channel → Placement → default 的優先序收斂；installation height、Floorplan origin 與 scale 由同一 Placement／Floorplan 共用。

productFocal = isVariFocal && fMin != null && fMax != null ? [fMin, fMax] : (fMin ?? fMax)
currentFocal = channel.focalLength ?? placement.focalLength ?? (Array.isArray(productFocal) ? productFocal[0] : productFocal)
currentTilt = channel.tiltAngle ?? placement.tiltAngle ?? 45°
hMeters = placement.installationHeight ?? 3 m

mountMode = placement.mountMode ?? ceiling
wallOrientation = mountMode === wall ? (placement.wallOrientation ?? 0°) : 0°
currentRotation = (channel.rotation ?? placement.rotation ?? 0°) + wallOrientation
pxPerMeter = 1 / mpp（mpp > 0）

收斂後每個 Channel 都有一份 optical input、hMeters、current tilt／focal／rotation、origin 與 pxPerMeter。缺值出口集中在 Fallbacks。

Source VPP-FLOW-E2 · VPP-FLOW-E3 · VPP-FALLBACK-E1

03

Current H/V FOV：spec、pinhole 與 zoom correction

水平與垂直逐軸判斷。Fixed-focal 有 scalar catalog FOV 時直接採用；該軸沒有 spec 時以 sensor dimension S 與 current focal f 求 theoretical pinhole FOV。

θpinhole(S, f) = 2 × atan(S / (2f)) × 180/π

Varifocal 只有在該軸同時具備完整 wide／tele spec endpoints 時才套 correction。令目前焦距在 range 中的位置為 z：

z = [clamp(f, fmin, fmax) − fmin] / max(fmax − fmin, ε)
Δwide = FOVwide − θpinhole(S, fmin)
Δtele = FOVtele − θpinhole(S, fmax)
wideWeight = (1 − z)9
currentAxisFov = θpinhole(S, f) + Δwide × wideWeight + Δtele × (1 − wideWeight)

這個 wide-end residual 權重只控制 correction 的過渡；完整結果同時混合 wide／tele 的 spec−theoretical residual，並在兩端命中 datasheet。缺少完整 endpoints 時回到本節 pinhole 路徑，詳見 fallback matrix。

Source VPP-FLOW-E3 · VPP-FLOW-E4 · VPP-FALLBACK-E3 · VPP-FALLBACK-E4

04

Current V-FOV → 地面近邊與遠邊

以安裝高度 h、current tilt 與完整垂直視角 V 求上下緣 ray 的對地角度和交點。

αnear = tilt + V/2 · αfar = tilt − V/2 · d = h / tan(α)

下緣通常形成 dNear，上緣形成 geometric dFar；Camera origin 到 dNear 是 blind area。若單一 edge angle ≤ 0°，只有該 ray 採 1000 m fallback，不代表 shape exit。tilt ≥ 89.9° 的對稱投影則在 Exceptions 定義。

Derived VPP-FLOW-E5 · Source VPP-FLOW-E9

05

Current H-FOV＋resolution → DORI 外緣

DORI 是同一個 2D FOV 內的影像密度分層，不是四個不同的 optical FOV，也不是辨識保證。VPP 以水平場景寬度與 resolution width 計算 PPM。

sceneWidth(d) = 2 × √(d² + h²) × tan(H/2)（H-FOV < 170°）
sceneWidth(d) = π × √(d² + h²)（H-FOV ≥ 170°）
PPM(d) = resolutionWidth / sceneWidth(d)

physicalWidth = resolutionWidth / ppmThreshold
r = physicalWidth / [2 × tan(H/2)]（H-FOV < 170°）
r = physicalWidth / π（H-FOV ≥ 170°）
dPPM = √(r² − h²)
DORI bandThreshold外緣政策
Identify280 PPM各產品皆計算
Recognize150 PPM各產品皆計算
Observe80 PPM一般 fixed-focal 的 dOuterDORI
Detect30 PPMVarifocal／PTZ Optical Zoom／Thermal 的 dOuterDORI

Thermal 的已確認差異只有 outer threshold；不可由此推論另一套 FOV 公式。H-FOV ≥ 170° 的分支只改 PPM／DORI physical width，不是 shape gate；Exceptions 僅交叉引用本節。

Derived VPP-FLOW-E6 · Source VPP-FLOW-E8 · VPP-FALLBACK-E6 · VPP-FALLBACK-E8

06

合流、footprint 與 Floorplan 2D shape

V-FOV branch 提供地面幾何邊界，DORI branch 提供影像密度外緣；較短者成為一般梯形的實際遠邊。

effectiveFar = min(dFar, dOuterDORI)
r(d) = √(d² + h²)
width(d) = 2 × r(d) × tan(H/2)

p1 = (−wNear/2, dNear) · p2 = (+wNear/2, dNear)
p3 = (+wFar/2, effectiveFar) · p4 = (−wFar/2, effectiveFar)

四個局部 meter 角點先乘 pxPerMeter，再套 φ = −currentRotation 與 Camera origin：

(xPx, yPx) = (xMeter, yMeter) × pxPerMeter
xRot = yPx × cosφ − xPx × sinφ
yRot = yPx × sinφ + xPx × cosφ
canvasPoint = originPx + (xRot, yRot)

一般輸出以 p1→p2→p3→p4 形成 Konva trapezoid，並疊加 DORI bands 與 blind area。wedge／circle 的 mode gate 見 Exceptions。

Source VPP-FLOW-E7

執行 npm run docs:vpp-ivsd 開啟 VPP fallback 與例外決策互動圖。

07

Fallbacks：缺值時停在哪裡或回到哪條路徑

條件結果Canonical definition
focal 全缺停止繪製，不產生 footprint。本列
sensor 無法換算使用 5.37 × 4.04 mm。本列
resolution 無效使用 1920 × 1080。本列
mpp 無效使用 1 px/m。本列
Fixed-focal 的該軸 spec 分流依 source-selection rule 處理。Current FOV source rule
Varifocal 的 endpoint 完整度依 correction guard 處理。Current FOV correction guard

Source VPP-FLOW-E1 · VPP-FLOW-E2 · VPP-FALLBACK-E1 · VPP-FALLBACK-E3 · VPP-FALLBACK-E4

08

Exceptions：projection 與 shape mode 的獨立判定

條件已確認行為
tilt ≥ 89.9°Ground projection 改為相機正下方的對稱結果：dNear = −h × tan(V/2) · dFar = +h × tan(V/2)。
edge angle ≤ 0°（1000 m case）只對該 ray 套用 ground-projection fallback；不切換 shape mode。
H-FOV ≥ 170°只有 PPM／DORI 使用 inverse DORI branch；不是 shape gate。
一般 perspective非 fisheye／panoramic 且 tilt > 0、height > 0 時走 ground projection 與 trapezoid。
FisheyeH=V=180°；tilt 90° 可成 360° circle，其他方向為 wedge。
Panoramic 或無一般地面條件Panoramic，或 tilt ≤ 0／height ≤ 0 時使用 wedge。
Thermal不另選 FOV；DORI outer edge 交由 DORI policy。

Fisheye／panoramic、near-vertical 與 edge-ray fallback 是相異判定；不能由其中一項推論另一項。

Source VPP-FLOW-E9 · VPP-FALLBACK-E6 · VPP-FALLBACK-E8 · VPP-FALLBACK-E9

09

Worked example：IB9387 的完整 calculation path

輸入為 IB9387-EHTV-V3、sensor 5.6 × 3.2 mm、focal range 2.7–13.5 mm、spec H 100.1–29.9°、spec V 71.8–22.4°；本次 current focal 6 mm、height 3 m、tilt 45°、rotation 0°、resolution 2560 × 1920。

步驟結果依據
1 · Current FOVPinhole 主曲線加 wide／tele endpoint correction，得到 H 56.56°、V 38.81°。Current FOV
2 · Groundαnear 64.40°、αfar 25.60°，得到 near 1.44 m、geometric far 6.26 m。Ground projection
3 · DORIgeometric far 處仍約 342.66 PPM，高於 Identify 280 PPM，DORI 不先截短。DORI
4 · Shape實際遠邊為 6.26 m；近邊寬約 3.58 m、遠邊寬約 7.47 m。Shape
5 · Floorplanmeter 四角點依 scale 與 rotation 轉成 pixel，形成近窄遠寬的 trapezoid。Shape

Calculation path VPP-FLOW-E4 · VPP-FLOW-E5 · VPP-FLOW-E6 · VPP-FLOW-E7