Equirect → Perspective

A 2:1 equirectangular panorama is a great way to store a scene and a terrible way to look at it. Everything off the horizontal centerline is stretched, horizons bow, and if you try to edit a face or a sign in that projection directly, the model sees a funhouse mirror version of reality. EquirectToPersp is the fix: it drops a virtual pinhole camera inside your panorama, points it where you tell it, and renders a flat, distortion-free photo you can actually work with.

What it does

Think of it as "take a screenshot from inside the sphere." You give it your 2:1 equirect, aim with yaw and pitch, pick a field of view, and it computes a rectilinear projection - the math is the same as a real camera lens: build a 3D rotation matrix from your yaw/pitch, generate a pinhole ray for every output pixel, and sample the equirect with GPU-accelerated bilinear interpolation (torch.grid_sample). Nothing is learned or generated; it's pure geometry, so it's instant.

The inputs

• image - the equirectangular panorama (2:1).
• yaw (-180 to 180) - horizontal look direction. 0 = straight ahead (center), ±180 = behind you. This is the knob you'll spin most.
• pitch (-90 to 90) - vertical look. Positive = up, negative = down.
• fov (10–150) - horizontal field of view in degrees. 90 is a standard "normal-ish" look; wider grabs more scene, narrower zooms in.
• output_width / output_height - output size in pixels (64–4096, default 1024×1024). Pick dimensions matching your editing tool.

The outputs - and why there are three

• perspective - the rendered rectilinear view. This is what you edit.
• equirect_passthrough - the original panorama, passed through untouched. Sounds redundant until you realize the composer needs it.
• projection_data (EQUIRECT_PROJECTION) - a tiny bundle carrying the yaw, pitch, fov, and output dimensions.

That last one is the part beginners miss. PerspToEquirect doesn't re-derive anything - it reads this data to know exactly how to reproject your edit. If you re-extract a view with different yaw after editing, you must also grab the matching new projection_data, or the patch will be composited using geometry that doesn't match your edited image.

Where it fits

The pack's flagship perspective-editing workflow:

Load Image -> EquirectToPersp -> Kontext Panorama Editor -> PerspToEquirect -> 360 Viewer

You extract the region you care about, paint a mask on the clean perspective view (Impact Pack's PreviewBridge → MaskEditor is the recommended route), edit it with Kontext (or anything else - it's just an image), and the composer stitches it back. The same node is also handy for plain "take a photo out of my panorama" duties - no editing involved.

Common issues

• Blurry extraction. You're sampling from a region of the source equirect; if output_width demands more detail than the source has there, it upscales nothing. Use an equirect with enough resolution for the crop you want.
• Extreme fov = weird edges. 150° captures most of your vision and the projection gets heavy at the borders. For editing, stay in the 70–110 range.
• Patch lands in the wrong place later → mismatched projection_data. Keep the extraction and composition in one straight-line path and this can't happen.