Fred's ImageMagick Scripts



    Licensing:

    Copyright © Fred Weinhaus

    My scripts are available free of charge for non-commercial use, ONLY.

    For use of my scripts in commercial (for-profit) environments or non-free applications, please contact me (Fred Weinhaus) for licensing arrangements. My email address is fmw at alink dot net.

    If you: 1) redistribute, 2) incorporate any of these scripts into other free applications or 3) reprogram them in another scripting language, then you must contact me for permission, especially if the result might be used in a commercial or for-profit environment.

    Usage, whether stated or not in the script, is restricted to the above licensing arrangements. It is also subject, in a subordinate manner, to the ImageMagick license, which can be found at: http://www.imagemagick.org/script/license.php

3DBOX


Generates a perspective view of a 3D box at any orientation with pictures pasted on each of its sides

Download Script

last modified: September 26, 2017

WARNING: This Script Is Limited To IM Version 6.3.5-6 Or Higher



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.


EXAMPLES


3 Square Images --- Variations In PEF (Perspective Exaggeration)

Original Images

Arguments:
pan=45 tilt=-45 pef=1
filter=point

Arguments:
pan=45 tilt=-45 pef=0.5
filter=point
(default pef)

Arguments:
pan=45 tilt=-45 pef=0
filter=point
(isometric)

Pan Animation
Arguments:
tilt=-45 pef=1
filter=point format=center

Pan Animation
Arguments:
tilt=-45 pef=0.5
filter=point format=center

Pan Animation
Arguments:
tilt=-45 pef=0
filter=point format=center



3 Square Images --- Pan Animations --- Variations In Mode

Pan Animation Script

Original Images

Pan Animation
Arguments:
tilt=-45 pef=0.5
filter=point filter=center
mode=mirror

Pan Animation
Arguments:
tilt=-45 pef=0.5
filter=point filter=center
mode=rot180

 
 


3 Square Images --- Tilt Animations --- Variations In Mode

Tilt Animation Script

Original Images

Tilt Animation
Arguments:
pan=45 pef=0.5
filter=point filter=center
mode=mirror

Tilt Animation
Arguments:
pan=45 pef=0.5
filter=point filter=center
mode=rot180

 
 


3 Square Images --- Variations In Zoom Or Size

Original Images

Arguments:
pan=45 tilt=-45 pef=0.5
filter=point zoom=1.5

 

Arguments:
pan=45 tilt=-45 pef=0.5
filter=point size=400x
(make width 400)

 

Arguments:
pan=45 tilt=-45 pef=0.5
filter=point size=x400
(make height 400)

 


Imagemagick Box: 3 Images --- Variations In PEF (Perspective Exaggeration)

Original Images
(see http://www.imagemagick.org/Usage/distorts/#box3d)


(box front)

(box spine)

(box top)

Arguments:
pan=45 tilt=-30 pef=1
filter=point

Arguments:
pan=45 tilt=-30 pef=0.5
filter=point
(default pef)

Arguments:
pan=45 tilt=-30 pef=0.01
filter=point
(virtually isometric)



Imagemagick Box: 3 Images --- Variations In Orientation

Original Images
(see http://www.imagemagick.org/Usage/distorts/#box3d)


(box front)

(box spine)

(box top)

Arguments:
pan=45 tilt=-60 pef=0.5
filter=point

Arguments:
pan=45 tilt=-45 pef=0.5
filter=point

Arguments:
pan=45 tilt=-30 pef=0.5
filter=point



What the script does is as follows:

  • Define world coordinates with Z pointing towards the viewer, X
    pointing to the right as seen by the viewer and Y pointing
    upwards as seen by the viewer
  • Creates a box whose world coordinates are the dimensions of
    the first 3 images and whose centroid is at the world coordinate origin
  • Defines surface corners from the vertices of box
  • Assign an image to each surface: Image1 will be on the front,
    Image2 will be on the left side and Image3 will be on the top
  • Projects the corners of the box to the output image domain
  • For each surface, create a set of 4 pairs of control points
    using the input image corner x,y coordinates and the projected
    box corner x,y coordinates for that surface
  • Test for backfacing surfaces and eliminate them
  • Apply +distort perspective to each front facing surface
    to warp the appropirate image onto its corresponding
    front facing surface