ZToWorldPos

ZToWorldPos относится к Position tools Fusion. Её задача — переводить один технический способ описания положения пикселя в другой: Z depth хранит расстояние относительно camera view, а World Position Pass хранит XYZ-положение точки в мировом пространстве сцены.

Главное исправление по сравнению со старой карточкой: у ноды не один универсальный Input. Официальная topology содержит обязательный Image input, обязательный Scene Input с 3D Camera и стандартный optional Effect Mask.

Image input принимает обычный Fusion image stream, но смысл технических данных внутри него зависит от Mode. Для Z to WorldPos во входном image должен существовать валидный Z channel; для WorldPos to Z нужен World Position Pass.

Grayscale depth-looking RGB и настоящий Z channel — не одно и то же. Если источник выглядит как чёрно-белая depth-карта, сначала проверьте, где реально хранятся глубинные данные и читает ли их Fusion как Z, а не просто как яркость RGB.

Scene Input принимает Camera3D либо 3D scene stream, содержащий камеру. Camera нужна для обеих направлений преобразования, потому что связь между image-space depth и world-space XYZ определяется projection/view transform конкретной камеры.

Камера должна соответствовать тому render/depth/WPP, который пришёл во входной Image. Случайная Camera3D может дать численно допустимый, но пространственно неправильный результат: world coordinates окажутся смещёнными/масштабированными или Z перестанет соответствовать исходной сцене.

Если в подключённом Scene Input несколько cameras, параметр Camera выбирает нужную модель. Это selector источника геометрии, а не регулятор силы depth и не способ 'подкрутить' World Position визуально.

В режиме Z to WorldPos нода использует Z + camera projection, чтобы восстановить, где каждый видимый пиксель находился в world space. По сути это back-projection из camera/depth representation обратно в XYZ сцены.

Качество полученного World Position ограничено качеством входного Z. Шумный, квантованный, дырявый или temporally unstable depth неизбежно превращается в шумные/дрожащие world coordinates; сама конвертация не восстанавливает потерянную геометрию.

Официальный manual отдельно отмечает полезный production-сценарий: если 3D-tracking software отдаёт per-pixel Z вместе с 3D Camera, ZToWorldPos может построить WPP и тем самым открыть Position-workflow вроде Volume Mask/Volume Fog для отснятой сцены.

В режиме WorldPos to Z операция идёт в обратную сторону: World Position Pass оценивается относительно выбранной Camera3D, и нода формирует соответствующий Z channel для этой camera view.

World Position Pass нельзя оценивать как обычную beauty-картинку. XYZ могут содержать отрицательные и очень большие значения; это координаты сцены, а не display-referred цвет.

Из-за большого диапазона world coordinates WPP должен сохраняться в 32-bit floating point. Нормализация или clamp в диапазон 0–1 может сделать preview красивее, но разрушить точные координаты для последующих Position tools.

Для визуализации WPP часто мыслят XYZ как RGB: X→R, Y→G, Z→B. Это удобная диагностика, но технический смысл остаётся пространственным; grading такой карты как обычного цвета меняет координаты.

Fusion Position tools ожидают World Position в World Space. Eye/Camera Space и Object/Model Space могут выглядеть похожими как цветные карты, но имеют другой смысл и не должны подменяться без явного преобразования координат.

Scene Input может получать не только голую Camera3D, но и 3D scene branch с одной или несколькими cameras. В таком случае Camera dropdown нужен именно для выбора той camera, которой соответствуют Image technical data.

Effect Mask — стандартный optional mask input. Он не заменяет Z/WPP и не приносит camera data; его задача — пространственно ограничить действие ZToWorldPos там, где conversion действительно нужен.

Пустые области World Position имеют отдельный риск: pixels без реальной geometry могут оказаться инициализированы как (0,0,0). Для 3D-render workflow manual рекомендует создавать дальние position values bounding sphere/box, если Position tools должны корректно воспринимать background.

Так называемый 'dark box' problem особенно заметен у volumetric/position effects: пустой фон с world position (0,0,0) может ошибочно читаться как точка в центре сцены. Это проблема исходного WPP coverage, а не ошибка параметра Camera в ZToWorldPos.

При Z→WorldPos для live-action/tracked footage похожая логика означает, что foreground-only depth недостаточен для задач, где downstream должен знать положение background. Отсутствующие depth samples не появляются автоматически после конвертации.

Не нормализуйте, не tone-map и не пропускайте технический WPP через обычный display transform до завершения spatial processing. Для просмотра можно сделать отдельную диагностическую ветку, сохранив production branch в float без творческих преобразований.

В обратном WorldPos→Z workflow исходный WPP должен относиться к той же world-coordinate system, что и connected camera. Даже корректный 32-bit WPP из другой сцены/трансформации не становится правильным только из-за совпадения разрешения кадра.

Разрешение и pixel correspondence тоже важны: Z/WPP описывают данные на конкретных pixels. Rescale/warp между генерацией pass и conversion требует осознанной обработки, иначе camera projection и technical data перестанут описывать одни и те же sample positions.

Round-trip Z→WorldPos→Z полезен как QC: он помогает выявить mismatch камеры, precision loss и повреждённые technical channels. Но требовать bit-exact identity не следует — pipeline precision, resampling и источник Z могут давать расхождения.

Для кэша/экспорта выбирайте формат и настройки, которые сохраняют нужную float precision и technical channels. Красивый RGB preview после file round-trip не доказывает, что WPP/Z сохранились без clamp или потери служебных данных.

Temporal QC обязателен, если Z или camera анимированы. Camera solve jitter, depth flicker и holes превращаются в дрожащие world positions, а затем — в плавающие VolumeMask/VolumeFog и другие пространственные эффекты.

Надёжный production-порядок: сначала подтвердить data contract Image + matching Camera3D, затем выбрать Mode, проверить raw technical result в float/full-range view, только после этого подключать Position/depth-aware downstream и в самом конце делать display-friendly preview.