Page MenuHome

[Cycles] Settings to restrict polar range for equirectangular panoramas
Closed, ResolvedPublicPATCH



For my current university project I need to create spherical panorama images for verifying an algorithm. In the real world those panorama images are created by a panoramic camera mounted on a mobile robot. Yet my real world images only contain a certain polar range, e.g. from the horizon at 0° to above the horizon at 30°, while the "equirectangular" panorama image setting in cycles produces images spanning from below the camera at -90° to above the camera at 90°.

Obviously, for producing useful images without wasting lots of render time on regions I don't really use, I needed to restrict the polar range.

Changes to the user:

The patch below adds two new input boxes when choosing the "equirectangular" image mode in cycles: "Elevation" and "Depression". "Elevation" is the angle between the camera horizon and the last row in the output image. "Depression" is the angle between the camera horizon and the upper edge of the output image. I've attached a small image (blender_depression_elevation_explained.svg) that should explain the two settings. The default settings are Elevation at -90° and Depression at 90° so no change to the original implementation should be visible.


Basically those two settings just remap the original output texture "v"-coordinate to a subset of that coordinate. It is equivalent to rendering the image at a higher resolution without the patch and then cropping everything above and below the desired range away. Remapping is done in the kernel functions "panorama_to_direction" and the inverse is done in "direction_to_panorama"; a few calculations are done in the "camera.cpp" code.

I've attached a few example images and an example scene. I hope this patch might be found useful. This is the first time I ever had a look at the blender source code and I am astonished how simple it was to add this feature.

All attached files are hereby public domain.

Event Timeline

Assigning to Dalai first, Dalai can you check on this? I guess Brecht should take a look too later. :)

Hi Andreas,

I like the patch, and I see myself using this. However, this is a not so common use case and this is doable in python (using Border Render to crop the effective render area). So I'm not sure it makes sense to be added in the core. And addon may work better in this case.

(and sorry about the long delay, I've been pondering about this since I saw the patch., but I wasn't so sure on how to phrase that)

I'm assigning to Brecht for his 2 cents.

Hi Dalai,

thank you for your response.

I wasn't aware of the "Border Render" functionality and it took me fifteen minutes and a glance at the documentation to find it. Despite from that I agree that "Border Render" plus a nifty Python Addon which does the tiresome calculations in the background would be a perfectly good solution.

Yet I see a few problems with this approach, which might be invalid, as I'm not very experienced with the capabilities of the Python API: In order to be as simple to use as possible the scene description containing the output image resolution has to be duplicated, as you want the user to set the actual output image resolution in the scene setup. Thus the addon has to transparently recalculate the output image resolution for the current render job, add the border range, but should not change these settings in the UI.

Additionally the Addon would have to "hook" into the "begin render event" -- I cannot imagine having an additional "Render Restricted Panoramic Image" button.

As I said, I cannot asses if these requirements can be met with a Python Addon.

An even better solution might be to change the code I've written to adapt the "border range" settings in the C++ code depending on the "elevation" and "depression" settings. This removes the need of adding two additional variables to the cycles kernel constants. Unfortunately I wont have time implementing (and more critical: testing and verifying) this until mid-august.

Thank you again and keep up the good work!


"Additionally the Addon would have to "hook" into the "begin render event" -- I cannot imagine having an additional "Render Restricted Panoramic Image" button."
That's totally doable in Python.

You can change the size before rendering, and re-change after rendering it.
Since we are talking about a equirectangular panorama, when you change the depression/elevation what you are doing is exactly that.
The approach in Python has a big advantage that it will make easier to keep the aspect ratio of the final image correct.

Otherwise with your patch one would need to calculate the correct height for the given angle range.

I think it makes sense to have these angles configurable as part of the core. I'd suggest to rename these to Vertical min/max and to add Horizontal min/max.

This came up in T39165: Cycles equirectangular panoramic camera missing Field-of-view settings.

Just to be clear, I'm fine with having this feature, just needs a better name and control for both vertical and horizontal min/max to be committable.

@Andreas Stöckel (aurelian15) : Hi, do you plan to finish this feature with the two things @Brecht Van Lommel (brecht) mentioned? Would be great to have the feature in trunk, this is the only camera type with no field-of-view settings. Thanks!

Thomas Dinges (dingto) changed the task status from Unknown Status to Resolved.Jan 21 2015, 7:55 AM
Thomas Dinges (dingto) claimed this task.

This has been implemented now, closing.