Fred's ImageMagick Scripts



    Licensing:

    Copyright © Fred Weinhaus

    My scripts are available free of charge for non-commercial (non-profit) 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

    Please read the Pointers For Use on my home page to properly install and customize my scripts.

3DROTATE


Applies a perspective distortion to an image by providing three rotation angles, zoom, offsets, background color, perspective exaggeration and auto zoom/centering

Download Script

last modified: October 25, 2020



USAGE: 3Drotate option=value infile outfile
USAGE: 3Drotate [-h or -help]

OPTIONS: any one or more

pan ...... value ... rotation about image vertical centerline;
.................... -180 to +180 (deg); default=0
tilt ..... value ... rotation about image horizontal centerline;
.................... -180 to +180 (deg); default=0
roll ..... value ... rotation about the image center;
.................... -180 to +180 (deg); default=0
pef ...... value ... perspective exaggeration factor;
.................... 0 to 3.19; default=1
idx ...... value ... +/- pixel displacement in rotation point right/left
.................... in input from center; default=0
idy ...... value ... +/- pixel displacement in rotation point down/up
.................... in input from center; default=0
odx ...... value ... +/- pixel displacement in rotation point right/left
.................... in output from center; default=0
ody ...... value ... +/- pixel displacement in rotation point down/up
.................... in output from center; default=0
zoom ..... value ... output zoom factor; where value > 1 means zoom in
.................... and < -1 means zoom out
bgcolor .. value ... the background color value; any valid IM image color
.................... specification (see -fill); default is black
skycolor . value ... the sky color value; any valid IM image
.................... color specification (see -fill); default is black
auto ..... c ....... center bounding box in output
.................... (odx and ody ignored)
auto ..... zc ...... zoom to fill and center bounding box in output
.................... (odx, ody and zoom ignored)
auto ..... out ..... creates an output image of size needed to hold
.................... the transformed image; (odx, ody and zoom ignored)
vp ....... value ... virtual-pixel method; any valid IM virtual-pixel method;
.................... default=background

PURPOSE: To apply a perspective distortion to an image by providing three rotation angles, zoom, offsets, background color, perspective exaggeration and auto zoom/centering.

DESCRIPTION: 3DROTATE applies a perspective distortion to an image by providing any combination of three optional rotation angle: pan, tilt and roll with optional offsets and zoom and with an optional control of the perspective exaggeration. The image is treated as if it were painted on the Z=0 ground plane. The picture plane is then rotated and then perspectively projected to a camera located a distance equal to the focal length above the ground plane looking straight down along the -Z direction.

ARGUMENTS:

PAN is a rotation of the image about its vertical centerline -180 to +180 degrees. Positive rotations turn the right side of the image away from the viewer and the left side towards the viewer. Zero is no rotation. A PAN of +/- 180 deg achieves the same results as -flip.

TILT is a rotation of the image about its horizontal centerline -180 to +180 degrees. Positive rotations turn the top of the image away from the viewer and the bottom towards the viewer. Zero is no rotation. A TILT of +/- 180 deg achieves the same results as -flop.

ROLL (like image rotation) is a rotation in the plane of the the image -180 to +180 degrees. Positive values are clockwise and negative values are counter-clockwise. Zero is no rotation. A ROLL of any angle achieves the same results as -rotate.

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

PEF is the perspective exaggeration factor. It ranges from 0 to 3.19. A normal perspective is achieved with the default of 1. As PEF is increased from one the perspective effect moves towards that of a wide angle lens (more distortion). If PEF is decreased from one the perspective effect moves towards a telephoto lens (less distortion). PEF of 0.5 achieves an effect close to no perspective distortion. PEF values too large may cause part of the image appear above the 'horizon' in the 'sky'.

IDX is the a pixel displacement of the rotation point in the input image from the image center. Positive values shift to the right along the sample direction; negative values shift to the left. The default=0 corresponds to the image center.

IDY is the a pixel displacement of the rotation point in the input image from the image center. Positive values shift to downward along the line direction; negative values shift upward. The default=0 corresponds to the image center.

ODX is the a pixel displacement from the center of the output image where one wants the corresponding input image rotation point to appear. Positive values shift to the right along the sample direction; negative values shift to the left. The default=0 corresponds to the output image center.

ODY is the a pixel displacement from the center of the output image where one wants the corresponding input image rotation point to appear. Positive values shift downward along the sample direction; negative values shift upward. The default=0 corresponds to the output image center.

ZOOM is the output image zoom factor. Values > 1 (zoomin) cause the image to appear closer; whereas values < -1 (zoomout) cause the image to appear further away.

BGCOLOR is the color of the background to use to fill where the output image is outside the area of the perspective of the input image. See the IM function -fill for color specifications. Note that when using rgb(r,g,b), this must be enclosed in quotes after the equal sign.

SKYCOLOR is the color to use in the 'sky' area above the perspective 'horizon'. See the IM function -fill for color specifications. Note that when using rgb(r,g,b), this must be enclosed in quotes after the equal sign.

AUTO can be either c, zc or out. If auto is c, then the resulting perspective of the input image will have its bounding box centered in the output image whose size will be the same as the input image. If auto is zc, then the resulting perspective of the input image will have its bounding box zoomed to fill its largest dimension to match the size of the the input image and the other dimension will be centered in the output. If auto is out, then the output image will be made as large or as small as needed to just fill out the transformed input image. If any of these are present, then the arguments OSHIFTX, OSHIFTY are ignored.

VP is the virtual-pixel method, which allows the image to be extended outside its bounds. For example, vp=background, then the background color is used to fill the area in the output image which is outside the perspective view of the input image. If vp=tile, then the perspective view will be tiled to fill the output image.

NOTE: The output image size will be the same as the input image size due to current limitations on -distort Perspective.

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


Original Image



Various Perspective Distortions Applied To Image
Rotation Angle Changes

arguments:
pan=45
auto=zc

arguments:
tilt=45
auto=zc

arguments:
roll=45
auto=zc

arguments:
pan=45
tilt=45
auto=zc



Various Perspective Distortions Applied To Image
Various Parameter Changes

tilt=45
(zoom=1; default)

arguments:
tilt=45
zoom=-1.5

arguments:
tilt=45
zoom=-2
odx=-15
ody=-35

arguments:
tilt=45
auto=zc
bgcolor=wheat

arguments:
tilt=45
auto=zc
vp=tile



Various Perspective Distortions Applied To Image
Perspective Exaggeration Factor Changes

arguments:
tilt=45
pef=0.5 (telephoto)
zoom=zc

arguments:
tilt=45
pef=1 (default)
zoom=zc

arguments:
tilt=45
pef=1.8 (wide angle)
zoom=zc

arguments:
tilt=45
pef=2.8 (too large)
zoom=zc



Enhanced Features With IM 6.3.6:
Higher Quality - Antialiasing
Sky Color (Above Horizon)
Output Size Different From Input

Sky Color
arguments:
tilt=75
bgcolor=green
skycolor=skyblue

Output Size
arguments:
tilt=60
zoom=out

Output Size
arguments:
tilt=75
zoom=out



Perspective Animations

Download Script



Comparison Of Perspective vs Bilinear Distortions
For Pan=30 and Tilt=30

Perspective

True Bilinear

Pseudo Bilinear

Peserves all straight lines from input

Preserves all horizontal and vertical straight lines from input, but diagonal lines get curved.

Does not preserve any straight lines from input.


What the script does is as follows:

  • Treats the image as if it is on the Z=0 plane
  • Rotates the corner coordinates of the image according to the
    rotation angles
  • Defines a field of view, fov=56 degrees (nominally) corresponding to
    the diagonal dimension of the image
  • Computes the corresponding focal length which is then taken as the
    distance of a fictitious camera above the picture along the Z
    direction which is capturing the resulting perspective picture.
  • Computes the rational linear forward (and inverse) transformation
    equation coefficients
  • Projects the rotated corner coordinates into the camera plane
    using the rational linear coefficients
  • Optionally computes the bounding box for these points
  • Optionally scales and offsets the bounding box to fill an image the size
    of the input image
  • Optionally uses the scaled and offset output picture coordinates with the
    input coordinates and feeds these to -distort perspective to
    compute the new output image

For the case of pan=30 and tilt=30, this is equivalent to:

  • convert mandril.jpg -virtual-pixel transparent -background black \
    -distort Perspective '0,0 127,0 127,127 0,127 27,0 112,35 126,127 0,115' \
    mandril_perspective_p30_t30.jpg