Presenting the Dome2rect Fulldome Tool

By , August 19, 2013 1:42 pm

Dome2rect v1.2 - November 25, 2014

by Andrew Hazelden

Overview

Dome2rect is a command line script that uses the open source Panotools library + MPRemap application to automate the process of converting image sequences between multiple panoramic formats. I created this script because I wanted to make it simpler to convert a fulldome movie trailer into a "flat screen" rectilinear format for posting on sites like YouTube.

Windows 7 is required to use the dome2rect tools.

About the Tool

I was inspired to make this after reading Jason Fletcher's blog post on converting fulldome movies for display on flat screens:
http://thefulldomeblog.com/2013/06/29/defishing-for-flat-screens/

Download

The dome2rect program is an open source program that is a free download. A sample fulldome image sequence is included.

dome2rect_v1.2.zip (68MB)

Installation

For the software to work it has to be expanded and moved to the folder:

C:\dome2rect

Image Conversion Example

The dome2rect conversion process works by reading fulldome formatted imagery from the C:\dome2rect\input folder and saving the converted rectilinear frames to the C:\dome2rect\output folder. Let's convert the included fulldome angular fisheye sample image sequence named (zosma.0000.jpg - zosma.0035.jpg) to a flattened rectilinear format.

Fulldome Sample Image

fulldome image sample

Step 1. Edit the batch script file dome2rect.bat using a text editor. Type in your current input and output image filenames.

Edit the script.

Step 2. Double click on the dome2rect.bat program to start the conversion process.

Run the dome2rect script.

Step 3. The script will start and begin converting the imagery. A progress screen displays the status as the mpremap utility converts the current frame. (When the program gets to the end of your image sequence you will get a generic warning indicating mpremap couldn't find the next image.)

dome2rect conversion process.

Step 4. When the conversion process is complete we can review the image sequence that was generated in the "output" folder. If you are running Windows 7 you can use the included review.bat movie viewer.

dome2rect.bat Output Image:

This image is the output from running a dome to rectillinear conversion.

This image was created using a dome to rectilinear conversion.

Converting 1080p HD Media to Fulldome

The rect2dome.bat script can be used to convert a 1080p HD JPEG or PNM image sequence into a fulldome formatted fisheye projection.

The final output image resolution and the image positioning is controlled by editing the rect2dome script in the C:\dome2rect\scripts\ folder.

A sample rectilinear to domemaster image sequence conversion, named rect2dome.0000.jpg to rect2dome.0035.jpg, is included in the C:\dome2rect\output folder.

rect2dome.bat Input Image:

This image is the output from running a rectillinear to dome conversion.

This is the input image for the rectilinear to dome conversion.

rect2dome.bat Output Image:

This image is the output from running a rectillinear to dome conversion.

This image was re-projected into a domemaster fisheye format.

When the rect2dome output image is viewed in a fulldome simulator it looks like this:
This is the 1080p to dome conversion in a fulldome simulator.

Note: The Domemaster Stereo shader tool "Dome Viewer" was used to preview the rect to dome conversion.


Batch Script Notes

The tool is an early alpha release and will be improved over time. Right now the only image format enabled for input/output is .jpg files and a UNIX .pnm image format. In the future all the common image/video formats could be supported since the FFMPEG library is used for format conversions.

I created the following example .bat scripts to show what is possible:

angular2cyl.bat
Converts a an angular fisheye image to a cylindrical image.

angular2latlong.bat
Converts an angular fisheye image to a latitude/longitude (equirectangular) image.

latlong2cyl.bat
Converts a latitude/longitude image to a cylindrical image.

latlong2dome.bat
Converts a latitude/longitude (equirectangular) image to a fulldome image.

latlong2rect.bat
Converts a latitude/longitude (equirectangular) image to a rectilinear image.

rect2dome.bat
Converts a rectilinear image to a fisheye image

review.bat
Simple playback program to view the image output. This tool uses ffmpeg's playback tool.

PT Conversion Scripts

Internally the image projections are done using the mpremap library by Helmut Dersch:
http://webuser.fh-furtwangen.de/~dersch/mp/MotionPanoramas.html

The conversion scripts are stored in the scripts/ folder and are written using the Panotools PT Stitcher syntax:
http://wiki.panotools.org/PTStitcher

This example panotools conversion script takes an equidistanst fisheye image and converts it to a 1920x1080p rectilinear image output. The image is rolled -10 degrees, and pitched 55 degrees.

This example panotools conversion script takes an angular fisheye image and converts it to a 2160x1080 cylindrical image output. The image is pitched 90 degrees.

This example panotools conversion script takes an angular fisheye image and converts it to a 2048x1024 latitude longitude (equirectangular) image output. The image is pitched 90 degrees.

This example panotools conversion script takes a latitude longitude (equirectangular) image and converts it to a 1920x1080p rectilinear image output.

This example panotools conversion script takes a latitude longitude (equirectangular) image and converts it to a 1080x1080 fulldome angular fisheye image output. The image is pitched -90 degrees.

Here is a quick summary of the PT Stitcher syntax:

 

Changing Input & Output File Names

To change the name of the input and output files you can edit the .bat scripts using a plain text editor. All image sequences start on frame number 0 (eg. 0.jpg)

To convert a single frame image enter the exact image name. (eg. image.jpg)

To convert an unpadded image sequence use the value %%d.jpg (eg. 9.jpg )

To convert an a 4 digit padded image sequence use the value %%.4d.jpg (eg: 0009.jpg)

If you want the dome2rect script to process a single frame for testing change the following code:

@set ptscript=dome2rect

@set input=input\zosma.0001.jpg

@set output=output\sequence.%%d.jpg

If you want the dome2rect script to process a 4 digit padded image sequence change the following code:

@set ptscript=dome2rect

@set input=input\zosma.%%.4d.jpg

@set output=output\sequence.%%d.jpg


About the Tool

I was inspired to make this after reading Jason Fletcher's blog post on converting fulldome movies for display on flat screens:
http://thefulldomeblog.com/2013/06/29/defishing-for-flat-screens/

Cheers,
Andrew Hazelden

Print Friendly

17 Responses to “Presenting the Dome2rect Fulldome Tool”

  1. Paul says:

    Looking forward to trying it out soon, great work!

  2. Andrew Hazelden says:

    Hi Paul.

    Thanks for taking a look at the dome2rect tool. I'd love to hear your feedback and suggestions. In the next version I hope to add support for more image/video formats using FFMPEG.

  3. Ahmet says:

    Hi,

    Excellent! Congratulations!

    Is there any software, that you can suggest, doing the opposite job? That is, converting a rectangular video to dome format.

  4. Andrew Hazelden says:

    Hi Ahmet.

    Here is a simple panotools style rectilinear to dome conversion script called rect2dome that should help get you started:
    http://www.andrewhazelden.com/projects/dome2rect/scripts/rect2dome

    You can place the panotools script in the dome2rect scripts folder:

    C:\dome2rect\scripts

    and run the script by changing line 27 in the dome2rect.bat file to read:

    @set ptscript=rect2dome

    The script includes examples for 4K, 2K, 1080p, and 960p fullframe fisheye image output. A pitch value between -60 and -45 degrees usually works well.

    Regards,
    Andrew

  5. Ahmet says:

    Amazing! Thank you very much!

  6. Naz says:

    Hello Andrew. Such a very nice work. Just want to ask something similar to Ahmet. Do this tutorial work just for plain images (.jpg, .png etc) files or can be work with video format directly (.avi, .mpg etc? Thanks.

  7. Andrew Hazelden says:

    Hi Naz.

    I've posted a new version 1.1 of the dome2rect tool that has improved support for converting 1080p rectilinear image sequences into a domemaster image format. At the moment the dome2rect tool still works on still images, and image sequences.

    Extracting frames directly from a video file and converting them using the mpremap utility requires the use of an "image pipe" and this is an area I need to learn more about.

    Cheers,
    Andrew

  8. Gregory says:

    Hi Andrew,

    This rect2Dome option sounds like exactly what I am looking for, but the download link links to the V1.0. Do you have an updated link?

  9. Andrew Hazelden says:

    Hi Gregory.
    Thanks for noticing the link error. I've updated the URL so you should be able to download the newer version with the rect2dome option.
    Cheers,
    Andrew

  10. Gregory says:

    Awesome, thank you. I am attempting to make my own full dome animations. I have been using Photoshop's Sphereize to do the fish eye conversion. Is this a similar function, or is the way I am currently doing it less accurate? Your blog has been very helpful. Thank you!

  11. Andrew Hazelden says:

    Hi Gregory.

    The most common format to use when preparing imagery for a fulldome theater is a "domemaster" formatted angular fisheye image which has a 180 degree field of view. This image type is easy to spot because it typically has black circular matting applied around the frame.

    When the audience sees a fulldome image projected in a unidirectional fulldome theater they are looking primarily at the content that is positioned in the lower center part of the frame which is known as the "sweet spot". If you are composing text or captions on your fulldome frame you should try and keep the captions positioned so the viewer doesn't have to pan their head to read the messages.

    Are you using Photoshop, After Effects, or a 3D package to create your original artwork?

    If you are preparing 2D animations regularly you might find it easier to use an After Effects plugin like the the Navegar Fulldome Plugin to do the conversions:
    http://software.multimeios.pt/fulldome/

    If you are rendering animations using a 3D package the fulldome blog has a list of native fisheye rendering tools:
    http://thefulldomeblog.com/2013/06/28/fisheye-lens-shader-options/

    Depending on how you are preparing your content you might also enjoy my Domemaster Photoshop Actions:
    http://www.andrewhazelden.com/blog/2012/11/domemaster-photoshop-actions-pack/

    If you are making something closer to a slideshow, I've prepared a fulldome optimized PowerPoint template with a matching Photoshop action for the image warping:
    http://www.andrewhazelden.com/blog/2013/06/powerpoint-dome-template/

    If you use the powerpoint dome template's bundled photoshop action with your own imagery, try and keep the important content out of the "pole zone" in the image (the top 1/3 of the templates frame area), as it will look a bit pinched when viewed in the fulldome theater.

  12. Gregory says:

    Hi Andrew,

    Thank you so much for all the help. It will probably be a combination of 3D animation in Autodesk Maya and some compositing effects in After effects. But I am trying to do it on a bit of a budget because I am doing it within the school system and the fewer software packages I have the buy the better. Our astronomy department is using one of the Digitalis systems with the Fisheye projector, so I was trying to create the fulldome master (getting the fisheye distortion) out of photoshop using the Sphereize filter. I had read that was an option at the link below. If this works well enough it will save me from having to buy the Full Dome plugin since we already have Adobe licenses. If that works, then most of what I need I can get from the photoshop plugins you linked above. I could just run them as a batch process action on the image sequences rendered from Maya.

    http://artandemergingtechnology.wordpress.com/2014/05/09/how-to-create-a-fulldome-master/

    As of now we will probably be rendering from Mental Ray or Maya Software, just because that is what my students are most familiar with, and I would like to incorporate this into some class projects for my 3d Animation class.

    Again, I want to thank you for being so helpful with all this. For such a large community of people working with fulldome systems, there is surprisingly little information on how to get started. It seemed that every link I clicked on kept leading me either to you of one or two other people who have been very forthcoming with information. So I want to thank you for helping out us noobs.

    Greg

  13. John Young says:

    Hi Andrew, Gregory, I've been working with a lot of students and video producers who are new to Fulldome production so I created a blog that discusses resources, work flow, and specifics for delivery of Fulldome format to our dome. Perhaps it may help somebody. there are currently 4 issues, each with different topics. A lot of the artists for the NWEAMO festival used the sphereize filter, and while it looks adequate for surrealistic material, it leaves a lot to be desired for live photography.

    http://spacetheater.wordpress.com/
    I'll try your script, it has promise.
    John

  14. cly3d says:

    This has been a great help, Andrew. Thanks for the insights and the scripts (and the detailed explanation on the projection mapping variables within PT stitch)

    I've been trying to get it to do a dome2Equirect (dome master image remapped to equirectangular), but not successful.
    The idea is to remap dome videos to equirectangular or cylindrical projection for VR devices (oculus, iphone vr eyewear etc)

    Could I request guidance on this?
    Kind Regards

  15. Andrew Hazelden says:

    Hi Cly3D.

    I've updated the Dome2rect tool to v1.2 and have added two new conversion scripts: angular2latlong.bat and angular2cyl.bat.

    I hope they can provide you with the details required for your project.

  16. cly3d says:

    Thanks so much Andrew!
    I'll download the new version and try out some experiments and reply back.

Leave a Reply

Note: Comments will have spelling errors corrected before they are posted. If you have a specific question please provide your email address so I can send you a direct reply.