VPP design tool · FOV calculation note

VPP Camera FOV：參數、公式與地面投影

本頁整理 VPP 目前的 2D FOV 流程：Camera 與使用者各提供哪些參數、VPP 依什麼順序計算、公式背後的幾何原理，以及結果如何成為平面圖上的梯形、扇形或圓形。用途是讓 IVSD 團隊理解並比對 VPP 現況；跨系統契約與待決事項另見「IVSD 對接討論」。

跳至章節
名詞速查Camera spec安裝參數Current FOV地面投影DORI 外緣梯形 footprintFloorplan 轉換數值案例特殊條件
VPP Camera FOV 技術流程VPP 取得目前視角後，平行計算垂直視角的地面近遠邊，以及水平視角和解析度的 DORI 距離；兩條結果在 effectiveFar 合流，再轉成平面圖上的 2D shape。 01 · INPUTCamera + Placementfocal · FOV · h · tilt · resolution逐 CHANNEL 整理 02 · CURRENT FOV取得當下 H/V FOVspec 或 sensor + focalcurrentFovH · currentFovV 03 · V-FOV BRANCH投影到地面h · tilt · currentFovVdNear · geometric dFar 03 · DORI BRANCH計算 DORI 距離currentFovH · resolutionWdIdentify…dOuterDORI 04 · MERGE決定實際遠邊與寬度min(dFar, dOuterDORI)near / far width · meter points 05 · 2D OUTPUT畫到 Floorplanorigin · rotation · scaletrapezoid / wedge / circle KEY CONTRACTV-FOV 決定幾何近遠邊；H-FOV 與解析度決定細節可維持多遠；兩者共同決定最後的 2D 外緣。
名詞

名詞速查

本節只定義資料層級、幾何結果與單位；欄位是否必要、缺值行為及計算方式分別放在第 01 與第 03 節。

名詞本頁定義在流程中的作用
Camera product specCamera 型號層級、與安裝位置無關的光學與能力資料。同型號的 Placement 共用；提供 focal、FOV、sensor、resolution 與產品類型。
Placement某一顆 Camera 在專案與 Floorplan 上的安裝實例。提供位置、高度、方向與目前焦距，決定視野從哪裡、如何落地。
Channel可獨立設定方向與焦距、並獨立計算的一個鏡頭或子視野。每個 Channel 產生自己的 Current FOV 與一個 2D FOV shape。
Resolved input套用 Channel override、Placement 值及 fallback 後，本次真正送進公式的一組參數。把不同資料來源收斂成單一 Channel 的計算輸入。
Spec H/V FOVDatasheet 提供的水平／垂直完整視角，單位為 degree；變焦機型可包含 wide／tele 端點。作為 Current FOV 的直接來源或變焦端點校正依據。
Current H/V FOV這個 Channel 在目前焦距下，這次計算實際使用的水平／垂直完整視角。V-FOV 用於地面投影；H-FOV 用於場景寬度、PPM 與 2D shape。
dNear / dFarV-FOV 下緣／上緣射線與地面的幾何交點，單位為 meter。描述視野在地面上的幾何起點與最遠可達位置。
Blind areaCamera origin 到 dNear 之間，視野下緣尚未落到地面的區域。是近端未覆蓋地面的區域，不代表整個 Camera FOV 都不可見。
PPM / DORIPPM 是每公尺可分到的水平 pixel；DORI 是 Detect、Observe、Recognize、Identify 四個影像密度層級。由 resolution width 與 H-FOV 反推每個層級能維持到多遠。
dOuterDORI依 VPP current policy 從 DORI 距離中選出的細節外緣，單位為 meter。一般 fixed-focal 選 80 PPM；varifocal、PTZ Optical Zoom 與 Thermal 選 30 PPM。
effectiveFar幾何遠邊與 DORI 外緣中的較短者：min(dFar,dOuterDORI)。作為一般梯形真正繪製的遠邊。
Floorplan scalempp 表示每個平面圖 image pixel 代表幾公尺；pxPerMeter=1/mpp。把 meter 幾何轉成 floorplan pixel，不改變光學 FOV。
2D FOV shape套用地面幾何與 DORI 外緣後，投影到 Floorplan 的未遮蔽 footprint。一般鏡頭為 trapezoid；特殊條件可能為 wedge 或 circle。
01

Camera product input 與 fallback

本節列出 VPP 產生 2D FOV 時讀取的 Camera 型號欄位。至少要有一個 focal 值才能進入計算；其他欄位雖有 fallback，但 fallback 只確保可以繪製，不保證結果符合該 Camera datasheet。

兩種完整度：最低可計算條件是至少一個 focal 值。若要盡量符合 datasheet，應另外提供對應的 H/V FOV、正確 sensor size、resolution 與 isVariFocal；變焦機型的 focal 與每一軸 FOV 應各自提供完整 wide／tele 端點。目前焦距不屬於 product spec，來自第 02 節的 Placement／Channel。

Camera product 欄位欄位定義格式／單位提供規則與缺值結果
focalLengthMin / Max鏡頭可用焦段的端點；Min 為 wide 端，Max 為 tele 端。number · mm至少一個必要。兩者都沒有時不產生 2D FOV；變焦機型應提供兩端，定焦機型提供一個值即可。
fovHorizontalMin / MaxDatasheet 的水平完整視角；Max 為 wide 端，Min 為 tele 端。number · degree選填。缺少時以 sensor width＋current focal 使用 pinhole 推算；變焦機型應兩端皆有或皆無。
fovVerticalMin / MaxDatasheet 的垂直完整視角；Max 為 wide 端，Min 為 tele 端。number · degree選填。缺少時以 sensor height＋current focal 使用 pinhole 推算；變焦機型應兩端皆有或皆無。
sensorSizeSensor optical format，用來取得水平與垂直有效尺寸。fraction string → width／height mm選填。未知或無法換算時使用 5.37×4.04 mm；會影響 pinhole FOV 與變焦端點校正。
maxResolutionCamera 可輸出的最大影像尺寸。WxH · pixel選填。無效時使用 1920×1080；目前只使用 width 計算 PPM／DORI，不改變光學 FOV。
isVariFocal宣告 focal 與 FOV Min／Max 是否代表一段可調整的 zoom range。boolean應提供；只有 true 才按變焦端點處理，否則視為 fixed-focal。PTZ Optical Zoom 目前也使用此語意。
modelTypeCamera 的產品分類。enum string特殊產品應提供；目前 thermal 會使用 30 PPM DORI 外緣。Fisheye／Panoramic 則由 H/V FOV 組合判斷。
channels同一台 Camera 可獨立計算的視野數量。integer選填，預設 1；大於 1 時，每個 Channel 分別取得目前 tilt、rotation 與 focal。
02

安裝狀態與每個 Channel 的計算參數

Camera product spec 描述型號能力；runtime input 描述這一顆的安裝、方向與目前焦段。VPP 會先套用 Channel 覆寫與預設值，整理出這個 Channel 本次計算要使用的參數，再交給第 03 節。

02-A · 外部提供的安裝與畫布參數

用途欄位外部格式／預設VPP 契約
地面投影installationHeightmeter · 預設 3正規化為 hMeters，用於 near／far、ground width 與 DORI distance。
地面投影tiltAngledegree · 預設 450° 為水平、90° 為垂直向下。
Current FOVfocalLengthmm · zoomable 預設 fMin目前 zoom snapshot；PTZ 若只有 zoom step／倍率，必須由上游先轉成 mm。
Floorplan positionx / yfloorplan image pixel · 必填Camera origin；所有 2D FOV 點以此位置為基準。
Canvas transformrotationdegree · 預設 0套在已完成的局部幾何上。
Mount policymountMode / wallOrientationceiling／wall · orientation 預設 0°Wall mount 時把 wallOrientation 加入最終 rotation；不改光學 FOV。
Floorplan scalemppmeter per image pixelmpp > 0 時 pxPerMeter=1/mpp；否則 fallback 1 px/m。與 canvas zoom 無關。

02-B · Channel 覆寫與預設值

currentTilt = channelSettings[i].tiltAngle ?? placement.tiltAngle ?? 45°
currentFocal = channelSettings[i].focalLength ?? placement.focalLength ?? productFocal
currentRotation = (channelSettings[i].rotation ?? placement.rotation ?? 0°) + wallOrientation

Channel scope：每個 Channel 分別決定 tilt、focal 與 rotation；installation height、floorplan origin 與 scale 仍由同一個 Placement／Floorplan 共用。

02-C · 公式實際使用的參數

本次 Channel 計算參數 = {
  Camera 規格: { focalSpec, fovHSpec, fovVSpec, sensorSizeMm, resolution, modelType },
  安裝狀態: { hMeters, currentTilt, currentFocalMm, currentRotation },
  平面圖: { originPx, pxPerMeter },
  channelIndex
}

高度單位：外部輸入與第 03 節公式一律使用 meter。

03

從相機參數到平面圖 FOV 的計算流程

VPP 先取得這個 Channel 當下的 H/V FOV；接著用 V-FOV 求地面近／遠邊，同時用 H-FOV 與 resolution 求 DORI 距離；兩項結果以 effectiveFar 合流，最後依 floorplan scale 與 rotation 畫成 2D FOV。

Camera 規格 + Placement / Channel
→ current H/V FOV
→ { V-FOV：dNear / dFar ｜ H-FOV + resolution：DORI distances }
→ effectiveFar + near / far width
→ meter 四角點 → floorplan pixel → 2D FOV
03-A

Current H/V FOV：資料分流與計算

FOV decision

目的：取得這個 Channel 在目前焦距下真正交給後續地面投影使用的水平與垂直視角。

先判斷 focal 與該軸 FOV spec 的組合

Focal input該軸 FOV inputCurrent FOV 行為
scalarscalar直接使用型錄提供的單一 FOV。
scalarundefined以 Sensor dimension＋目前 focal 使用 pinhole 公式推算。
[fMin, fMax][wide, tele]以 pinhole 為基礎，混合 wide／tele 兩端的型錄差值。
[fMin, fMax]undefined以目前 focal 使用 pinhole 公式推算。

不完整端點不是支援契約：Varifocal 若只提供單一 FOV 端點，product transform 會產生 scalar；現行水平計算忽略該 scalar 並退回 pinhole，垂直計算卻直接採用 scalar。這是 H/V 不一致的相容行為；跨系統契約應要求每一軸「兩端皆有」或「兩端皆無」。

Fisheye 例外：水平 FOV 在 tilt 0°／90° 會優先回傳 180°／360°，不走上表的一般分流；詳見第 05 節。

公式符號與來源

符號代表內容來源
S該軸使用的 Sensor 尺寸；水平用 width，垂直用 height。Camera product spec
f這個 Channel 的目前焦距。第 02 節的 currentFocalMm
fMin / fMaxwide 端與 tele 端的焦距。focalLengthMin / Max
FOVwide / FOVtele原廠提供的 wide／tele 視角；數值分別來自 FOV Max／Min。該軸的 FOV product spec
θpinhole由 Sensor 尺寸與焦距推算的理論針孔視角。本步驟計算值
ε避免 focal range 為 0 時除以 0的極小正數。計算保護值

Case A · 沒有 H/V FOV：使用 pinhole

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

currentFovH = θpinhole(sensorWidth, currentFocal)
currentFovV = θpinhole(sensorHeight, currentFocal)

怎麼讀：Sensor 越大，視角越大；焦距越長，視角越小。這是 ideal pinhole FOV，不保證完全等於原廠鏡頭的實測值。

Case B · 有 wide／tele FOV：分三步修正

Step 1 · 目前焦距位於 zoom range 的哪裡

z = [clamp(f,fmin,fmax) − fmin]
    / max(fmax − fmin, ε)

z = 0 → wide 端　　z = 1 → tele 端

Step 2 · 計算型錄端點與 pinhole 端點的差值

wideCorrection = FOVwide − θpinhole(S,fmin)
teleCorrection = FOVtele − θpinhole(S,fmax)

Step 3 · 把兩端修正量加回目前的 pinhole FOV

wideWeight = (1 − z)9
teleWeight = 1 − wideWeight

currentAxisFov = θpinhole(S,f)
  + wideCorrection × wideWeight
  + teleCorrection × teleWeight

本步輸出

currentFovH · currentFovV

逐軸判斷：水平與垂直分開判斷；某一軸完全缺少 FOV spec 時，只有該軸退回對應 sensor dimension＋current focal。

與 PTZ 的關係：Portal 目前以 isVariFocal 將一般 Vari-focal 與 PTZ Optical Zoom 收斂到同一路徑；這裡只依目前焦距重算 current FOV，不處理 Pan 或 Tilt。

Pinhole FOV 幾何示意Sensor dimension、焦距與半視角形成直角三角形，因此完整視角是二乘以反正切 sensor dimension 除以兩倍焦距。 SENSOR PLANELENS focal length fSθ/2SCENE EDGE GEOMETRYtan(θ/2) = (S/2) / fθ = 2 × atan(S / 2f)Horizontal：S = sensor widthVertical：S = sensor height
Pinhole 公式只負責從 sensor dimension 與 focal 得到 ideal H/V FOV；原廠有提供 FOV spec 時，VPP 會依 fixed／zoomable 規則使用或修正它。
03-B

V-FOV 地面投影

Side-view geometry

目的：把垂直視角的下緣與上緣投影到地面，得到 Camera 前方的幾何近邊與遠邊。

使用參數

hMeters · currentTilt · currentFovV

Step 1 · 求視野下緣與上緣的對地角度

αnear = currentTilt + currentFovV/2
αfar = currentTilt − currentFovV/2

Step 2 · 求兩條射線的地面交點

dNear = hMeters / tan(αnear)
dFar = hMeters / tan(αfar)

本步輸出

dNear · dFar · blindArea = Camera origin → dNear

邊界行為：視線沒有落到地面時不走一般梯形；接近垂直向下時，近遠邊改為相機正下方兩側的對稱投影。

03-C

Resolution、PPM 與 DORI 外緣

Image density

目的：把水平解析度換成地面上的影像密度，反推出各 DORI 門檻最多能維持到多遠。

使用參數

hMeters · currentFovH · resolutionWidth · isVarifocalForDORI · modelType
isVarifocalForDORI = Array.isArray(focalSpec)

Step 1 · 已知距離，先求該處涵蓋的場景寬度與 PPM

sceneWidth(d) = 2 × √(d²+hMeters²) × tan(currentFovH/2)
PPM(d) = resolutionWidth / sceneWidth(d)

Step 2 · 已知 PPM 門檻，反求可維持的地面距離

physicalWidth = resolutionWidth / ppmThreshold
r = physicalWidth / [2 × tan(currentFovH/2)]
dPPM = √(r² − hMeters²)

本步輸出

dIdentify · dRecognize · dObserve · dOuterDORI

外緣選擇：一般 fixed-focal 使用 80 PPM 外緣；varifocal、PTZ Optical Zoom 與 Thermal 使用 30 PPM 外緣。H-FOV 接近 180° 時改用超廣角距離算法，避免一般 tangent 公式發散。

VPP DORI 分層與外緣政策相機附近的 Identify 區域具有最高 PPM，向外依序為 Recognize、Observe 與 Detect；固定焦相機外緣截在 Observe，變焦與 Thermal 保留 Detect 外緣。 DORI LAYERS · TOP VIEW 距離越近，PPM 越高；能看見的細節越多 GEOMETRIC dFar dOuterDORI = effectiveFar BLIND CAMERA GROUND DISTANCE Identify Recognize Observe Detect WHAT EACH BAND MEANS Identify · 280 PPM規劃上需要臉孔、車牌等細節的最近區域 Recognize · 150 PPM規劃上可辨認是否為特定人物 Observe · 80 PPM規劃上可觀察人形輪廓與動作 Detect · 30 PPM規劃上可判斷畫面中是否有物體出現 VPP DISPLAY POLICY · WHICH BAND BECOMES THE OUTER EDGE? 一般 Fixed-focal 外緣使用 Observe 80 PPM；Detect distance = Observe distance， 因此 30–80 PPM 的 Detect band 寬度為 0，不顯示。 Varifocal／PTZ Optical Zoom／Thermal 外緣使用 Detect 30 PPM，保留 Identify、Recognize、 Observe、Detect 四層；Thermal 是 fixed-focal 的產品例外。 NEXT · effectiveFar = min(geometric far, selected DORI outer edge)
DORI 是同一個 2D FOV 內由近到遠的細節分層，不是四個不同的 Camera FOV。四個門檻各自反推一個 ground distance；繪製時由外向內疊上較高 PPM 的區域，再以 effectiveFar 裁切。30／80／150／280 PPM 是目前使用的分層門檻，不代表實際場景中的辨識保證。
03-D

合流成最終梯形 footprint

Ground footprint

目的：把 V-FOV 的幾何遠邊與 DORI 的細節外緣合併，再求出平面圖梯形的四個角點。

使用參數

dNear · dFar · dOuterDORI · hMeters · currentFovH

Step 1 · 選出實際繪製的外緣

effectiveFar = min(dFar, dOuterDORI)

Step 2 · 求近邊與遠邊寬度

r(d) = √(d² + hMeters²)
width(d) = 2 × r(d) × tan(currentFovH/2)
wNear = width(dNear)
wFar = width(effectiveFar)

Step 3 · 建立 meter 局部座標的四個角點

p1 = (−wNear/2, dNear)
p2 = (+wNear/2, dNear)
p3 = (+wFar/2, effectiveFar)
p4 = (−wFar/2, effectiveFar)
VPP 地面投影與梯形幾何左側視圖說明 height、tilt 與 vertical FOV 如何得到 near 和 far；右側俯視圖說明 horizontal FOV 如何得到近遠邊寬度與四個梯形角點。 SIDE VIEW · VERTICAL FOV GROUND h dNear dFar tilt αnear = tilt + V/2αfar = tilt − V/2BLIND AREA TOP VIEW · HORIZONTAL FOV CAMERA ORIGIN wNear wFar H-FOV p1p2p3p4 effectiveFarLOCAL +Y / FORWARD
V-FOV branch 產生 near／far；H-FOV＋resolution branch 產生 DORI 外緣；兩者在 effectiveFar=min(dFar,dOuterDORI) 合流，再形成近窄遠寬的梯形。
03-E

Floorplan 座標轉換與 2D shape

2D output

目的：把以公尺表示的局部梯形轉成平面圖 pixel，再套用 Camera 的方位與位置。

使用參數

p1…p4 (meter) · pxPerMeter · currentRotation · originPx

Step 1 · 公尺轉為平面圖 pixel

(xPx, yPx) = (xMeter, yMeter) × pxPerMeter

Step 2 · 套用方向與 Camera origin

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

本步輸出

floorplan points · trapezoid / wedge / circle · DORI bands · blind area
04

兩種 limiting factor 的數值案例

第一個案例由 V-FOV 幾何遠邊限制；第二個簡例由 DORI 外緣先截短。兩者共同說明 effectiveFar 為什麼要取較小值。

04-A · IB9387：Vertical geometry 先限制遠邊

sensor 5.6×3.2 mmfocal 2.7–13.5 mmspec H 100.1–29.9°spec V 71.8–22.4°
1取得目前 FOV

以 6 mm pinhole 結果為主，再套 wide／tele 端點修正，得到 H 56.56°、V 38.81°。

2投影垂直上下緣

αnear=64.40°、αfar=25.60°，得到 near 1.44 m、geometric far 6.26 m。

3計算 DORI 外緣

幾何遠邊仍約 342.66 PPM，高於 Identify 280 PPM，因此 DORI distance 不會先截短視野。

4合流並求梯形寬度

effectiveFar 取 geometric far 6.26 m；以斜距與 H-FOV 得到近邊約 3.58 m、遠邊約 7.47 m。

5轉成 floorplan pixel

四個 meter 角點乘 pxPerMeter；rotation 0° 不轉向，最後形成平面圖梯形。

04-B

DORI 外緣先截短的簡例

DORI limited

目的：用一組容易驗算的參數，展示解析度不足以支撐到幾何遠邊時，2D shape 如何提早結束。

輸入

fixed-focal · current FOV = 90° × 30°
h = 3 m · tilt = 20° · resolutionW = 1920 px
fixed-focal outer threshold = 80 PPM

兩條分支

geometricFar = 3 / tan(20° − 30°/2) = 34.29 m

80 PPM 可涵蓋的場景寬度 = 1920 / 80 = 24 m
對應斜距 r = 24 / [2 × tan(90°/2)] = 12 m
dOuterDORI = √(12² − 3²) = 11.62 m

合流結果

effectiveFar = min(34.29, 11.62) = 11.62 m
05

特殊條件與產品分支

以下矩陣只整理會改變角度、外緣或 2D shape 的行為；未列出的 Camera 使用第 03 節一般梯形流程。

條件判斷方式Current FOV／地面行為2D shape 與 DORI
FisheyefovH = 180° 且 fovV = 180°tilt 90° 時 H-FOV 為 360°；其他 tilt 使用 180°。V-FOV 維持 180°。90° 向下畫 circle；其他方向畫 180° wedge。fixed-focal 外緣使用 80 PPM。
Panoramic／ultra-widefovH ≥ 180° 且 fovV < 180°不使用一般梯形的 tangent 展寬；DORI 距離不超過幾何 dFar。畫 wedge；外緣依 fixed／varifocal 的 80／30 PPM 規則後，再受 dFar 限制。
Multi-channelchannels > 1每個 Channel 使用自己的 tilt、rotation、focal 重跑完整流程。每個 Channel 各產生一個 shape；產品規格與安裝高度共用。
ThermalmodelType = thermal光學 FOV 與地面投影仍依一般公式。外緣保留到 Detect 30 PPM；shape 仍由 FOV 與安裝狀態決定。
視線未落地Camera 水平／向上，或安裝高度無法形成地面投影不建立一般 near／far 梯形。改以 wedge／circle 表示方向與範圍。
垂直向下tilt 接近 90°近遠邊改成相機正下方兩側的對稱投影。一般鏡頭形成對稱 footprint；Fisheye 為 360° circle。

文件邊界：本表描述 VPP 目前可觀察的 2D 行為；IVSD 要支援哪些分支、欄位如何表示與容許誤差，統一在「IVSD 對接討論」決定。

06

本文件的輸出與範圍

本頁到 2D FOV shape 為止；VPP 內部檔案、舊資料轉換與渲染元件不屬於跨系統說明內容。

範圍內容下一步
本頁涵蓋Current H/V FOV、地面 near／far、DORI distances、effectiveFar、floorplan points 與 shape type。可用來向 IVSD 說明及比對 VPP current spec。
本頁不涵蓋牆體遮蔽、API payload、canonical I/O schema、跨系統 parity 與驗收誤差。不應從本頁公式自行推定整合契約。
對接決策IVSD 支援機種、必填欄位、legacy 行為是否保留，以及 Golden Models。請見 IVSD 對接討論。