normals_from_depth — 3D `range_image` op

• 데이터 종류: depth → normalmap

• 호출: import fullseye as fs; fs.ledger.normals_from_depth(depth, fx=None, fy=None, cx=None, cy=None, orient_to_camera=True, spacing=None)(구현을 직접 호출하려면 import range_image; range_image.normals_from_depth(depth, fx=None, fy=None, cx=None, cy=None, orient_to_camera=True, spacing=None), 원장에서 가져오려면 ops3d.get("normals_from_depth"))

사용법

organized 깊이 → 방향이 붙은 단위 법선 (H,W,3). 이웃 화소의 3D 점의 외적(격자 구조 이용, O(HW)).

> 아래 상세 설명은 원문입니다 —— 요약과 제목은 번역되어 있습니다.

fx,fy 指定で透視、未指定で正射。orient_to_camera=True で法線をカメラ(原点)向きに符号統一。

★同名の別関数が 1 行ファサードにある。`fullseye.normals_from_depth` は

`(depth, K, smooth=0) の**透視版で K が必須**、こちら(fullseye.ledger`

経由 = `range_image`)は K を取らない正射版。片方の呼び方を覚えると、もう

片方で `TypeError` になる(2026-09-08 実測)。

★`spacing=(dy, dx) は**正射モードでの画素の実寸**。既定 None` は

「1 画素 = 1 単位」で、**異方な格子(例: 列 0.05 mm × 行 0.5 mm)をそのまま

渡すと傾きが黙ってずれる** —— 実測で x 成分が 20 倍(= 1/dx 倍)外れ、例外も

警告も出なかった。実寸が分かっているなら必ず渡すこと。透視モード

(`fx/fy` 指定)では焦点距離が実寸を決めるので無視される。

★`spacing を渡すときは **orient_to_camera=False`** にすること。正射での

「カメラ」は原点(左上・深度 0)という便宜的なもので、実寸を入れると面に対する

その位置が変わり、符号が反転しうる(実測: 傾き 0.1 の平面で

`orient_to_camera=False なら真値 x=-0.0995 と一致、True` では +0.0995)。

向きが要るなら、視線が定義できる座標系で後段で揃える。

法線は隣接画素の外積で出すため両軸に近傍が要る。H<2 or W<2 は第2の接線方向が無く

法線が定義できない(その軸の勾配を 0 とみなすと cross(dPx,0)=[0,0,0] の縮退法線を

静かに返してしまう)。fail-closed で明示的に ValueError 拒否する。

計算は `depth_to_organized_points で 3-D 点 P を作り、np.gradient` の列方向

差分 `dPx と行方向差分 dPy の外積 dPx × dPy` を単位長にする(端は片側差分)。

`orient_to_camera=True では n·(-P) < 0` の画素を反転し、法線が原点(カメラ)を向く

よう揃える。正射モード(`fx か fy が None)では P=(u,v,d)` なので原点は画像

左上の深度 0 の位置になり、「カメラ向き」の意味が透視モードと異なる点に注意。`cx`・

`cy` 省略時は画像中心。深度の段差(遮蔽エッジ)をまたぐ画素では外積が段差の向きを

拾って法線が壊れるので、`occlusion_edges` で境界画素を除いてから使う。深度 0 / NaN の

画素は検証せず、法線も不定になる。返り値は float32 の `(H,W,3)`。

배경 지식 가이드(이 연산자 앞에 있는 물리·규약)

• blender_interop — Blender との併用 — 形を作って fullseye で測る(軸・単位・正解データの罠)

• depth_sensors — 深度センサの知識 — 測距原理・実機の値・欠測の出方

참고(샘플 데이터·문헌)

• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.

• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.

실행 가능한 예제(이 연산자를 실제로 호출하는 검증된 샘플)

• range_image — py -3.11 examples_3d/range_image.py

타입이 이어지는 다음 연산자(`normalmap` 를 입력으로 받는 것)

fuse_to_voxel · render_shaded · phong_shade · matcap_shade · brdf_lommel_seeliger · brdf_hapke · bump_normals_fbm · integrate_normals

같은 카테고리(`range_image`)

depth_to_organized_points · occlusion_edges · bearing_angle_image

*Provenance: range_image.py — 3D 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*

normals_from_depth — 3D range_image op

사용법