USAGE: 3Dbox option=value infile1 infile2 infile3 [infile4 infile5 infile6] outfile
USAGE: 3Dbox [-h or -help]

OPTIONS: any one or more

pan ..... value ... rotation about output vertical centerline;
................... -360 to +360 (deg); default=0
tilt .... value ... rotation about output horizontal centerline;
................... -360 to +360 (deg); default=0
roll .... value ... rotation about the output center;
................... -360 to +360 (deg); default=0
pef ..... value ... perspective exaggeration factor;
................... 0 to 3.19; default=1
mode .... value ... mode for display of opposite faces to
................... image1, image2, image3;
................... mode may be either mirror or rot180; default=mirror
format .. value ... controls format of output image;
................... format may be either auto or center; default=auto;
................... auto sizes the output image to just contain the box;
................... center creates an output image large enought to
................... hold any rotation of the box and keep the centroid
................... of the box in the very center of the output image
zoom .... value ... output zoom factor; where value > 1 means enlarge
................... and < 1 means shrink
size .... value ... dwidth[xdheight] for the output image; options are:
................... dwidth, dwidthx, xdheight or dwidhtxdheight
bgcolor . value ... the background color value; any valid IM image
................... color specification (see -fill); default is black
filter .. value ... any valid IM filter method; default is area resampled.

If infile4 infile5 infile6 are left off, then the first three infiles
will be used for their opposite sides. The dimensions of all the images
must be consistent with forming a box.

PURPOSE: To generate a perspective view of a 3D box at any orientation with pictures pasted on each of its sides.

DESCRIPTION: 3D box generates a perspective view of a 3D box at any orientation with pictures pasted on each of its sides. The use may supply either 3 or 6 images. If only 3 images are provided, then these will be either mirrored or rotated 180 degrees for use on the opposite faces of the box. Note that the dimensions of all the images must be consistent with forming a box.

ARGUMENTS:

PAN is a rotation of the box about the output image vertical centerline -360 to +360 degrees. Positive rotations turn the right side of the box away from the viewer and the left side towards the viewer. If pan=0, tilt=0 and roll=0, the output image will look straight onto the side of the box containing the first image. The default is pan=0 degrees.

TILT is a rotation of the box about the output image horizontal centerline -360 to +360 degrees. Positive rotations turn the top of the box away from the viewer and the bottom towards the viewer. If pan=0, tilt=0 and roll=0, the output image will look straight onto the side of the box containing the first image. The default is tilt=0 degrees.

ROLL is a rotation in the box in the plane of the output image -360 to +360 degrees. Positive values are clockwise and negative values are counter-clockwise. If pan=0, tilt=0 and roll=0, the output image will look straight onto the side of the box containing the first image. The default is roll=0 degrees.

PAN, TILT and ROLL are order dependent. If all three are provided, then they will be done in whatever order specified.

PEF is the perspective exaggeration factor. It ranges from 0 to 3.19. A normal perspective is achieved with a value of 1. As PEF is increased from 1, the perspective effect moves towards that of a wide angle lens (more distortion). If PEF is decreased from 1 the perspective effect moves towards a telephoto lens (less distortion). A PEF=0, achieves an isometric (orthographic) view (parallel lines remain parallel). The default is 0.5 so as to avoid too much perspective exaggeration.

MODE identifies how to handle the images on the opposite faces to those for infile1 infile2 and infile3. This is especially useful when the other 3 images are not provided. In this case, it replicates the first 3 images for use as the remaining 3 images. The choices are either mirror or rot180. For mode=mirror, the opposite sides of the box will be mirror images with the tops aligned, when the other 3 images are not provide. When the other 3 images are provided, then they will be used as supplied. For mode=rot180, the opposite sides of the box will use 180 degree rotated versions of the first 3 images, when the other 3 images are not provided. When the other 3 images are provided, then they also will be rotated 180 degrees. The choice of mode, especially when the last 3 images are not provided, will be useful depending upon how the box is rotated and whether one wants to see right-side up images or upside down images. The default is mirror.

FORMAT identifies how to set the output image size. The choices are auto and center. When format=auto, the output image will be just large enough to contain the box. When format=center, the output image will be large enough to hold the box at any rotation, pef and zoom and keep the centroid of the box in the very center of the output image. This is important when trying to generate animations in order to keep the box properly rotating about a single centered point in the output image.

ZOOM is the output image zoom factor, which makes the output image larger or smaller in size. Values > 1 enlarge the output image; whereas values < 1 shrink the output image. The default is 1. The actual size of the image depends upon the box's rotation, zoom, pef and the format parameter.

SIZE is the dwidth[xdheight] for the output image. The choices are: dwidth, dwidthx, xdheight or dwidthxdheight. For format=auto, size will override zoom and determine the zoom factor to use to ensure the output is the desired size according to the following. If dwidth is provided, then it will be used to compute the zoom from the larger of the unzoomed output width and height. If dwidthx is provided, then it will be used to compute the zoom from the unzoomed output width. If xdheight is provided, it will be used to compute the zoom from the unzoomed output height. If dwidthxdheight is provided, dwidth will be used to compute the zoom from the unzoomed output width. The choice is basically determining which dimension will end up the desired size. For format=center, zoom and dwidth[xdheight] act independently. The default size is an approximaton and will be large enough to hold the box at any rotation, zoom and pef and may contain excess background. The size parameter, however, allows one to set a desired size. If either dwidth or dheight is missing, then the supplied value will be used for both the width and height of the output. The best way to determine the needed size is probably to generate an image with pan and tilt set to some multiple of 90 degrees and set the roll to 45 degrees so that output is looking right at the largest face turned so that the diagonals are horizontal and vertical. Then compare the size of this image to another generated with pan=45 degrees, tilt=-45 degrees and roll=0 so that one is viewing the box with its diagonals horizontal and vertical. Use the largest dimensions from each case. Basically, you can set dwidthxdheight such that the image will be larger than necessary as one can always crop the animation afterwards to remove excess background area.

FILTER is any valid IM -filter value. The default is (EWA) area resampling. This may cause slight blurring. If you prefer the result to be more crisp, but with the possibility of some aliasing, then use filter=point; otherwise for a compromise, use filter=lanczos.

NOTE: the script is a bit slow due to all the necessary setup computations prior to using +distort perspective to warp the images onto the box faces.

IMPORTANT: This script is limited to IM version 6.4.2-7 or higher to support -fx scientific-notation and IM version 6.3.5-6 or higher to conform to the current +distort perspective control point sequence.

NOTE: This script is built upon the excellent box example first developed by Anthony Thyssen at http://www.imagemagick.org/Usage/distorts/#box3d. I want to express my thanks to Anthony for his explainations of the subtle points of +distort perspective, -layers merge, -crop -flatten and the Unix eval expression.

Mathematics Background (32KB PDF)

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.