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

BUBBLEWARP


Applies or reverses a warp of an image onto a bubble.

Download Script

last modified: April 25, 2015



USAGE: bubblewarp ["osx,dx,isx,iox [osy,dy,isy,ioy]"] [-t type] [-m mode] [-f format] [-v vp] [-c vpcolor] [-b bgcolor] infile outfile
USAGE: bubblewarp [-h or -help]

osx,dx,isx,iox ...... x dimension parameters;
..................... osx=output scale factor; dx=distortion factor;
..................... isx=input scale factor; iox=input offset;
..................... osx=1,dx=1,isx=1,iox=0 are default values;
..................... osx,dx,isx,iox are floating point values;
osy,dy,isy,ioy ...... y dimension parameters;
..................... osy=output scale factor; dy=distortion factor;
..................... isy=input scale factor; ioy=input offset;
..................... osy=1,dy=1,isy=1,ioy=0 are default values;
..................... osy,dy,isy,ioy are floating point values;
-t .... type ........ type=arcsin or sin; default=arcsin
-m .... mode ........ mode=polar of rect; polar is a radial warp;
..................... rect is a separate warp in x and y;
..................... default is polar
-f .... format ...... format=circ or oval; circle produces a sphere
..................... within the bounds of the minimum of width or
..................... height; oval produces an ellipsoid which spans
..................... the width and height if not equal dimensions;
..................... default=circv
-v .... vp .......... vp is the virtual-pixel method; default=black
-c .... vpcolor ..... vpcolor is the color for the case when
..................... -virtual-pixel=background; this is where parts
..................... of the sphere map outside image; default is black
-b .... bgcolor ..... bgcolor is the color for the area outside the
..................... circular area of the sphere; default is black

Note: if only one set of values are provided, then they
will be used for both dimensions. Enclose the set of
coefficients in double quotes and separate the two sets
with a space.

PURPOSE: To apply or reverse a warp to an image onto a bubble.

DESCRIPTION: BUBBLEWARP is designed to apply an arcsin or sin function warp to an image. If mode is polar, the arcsin warps the image onto a hemisphere and the sin will "reverse" or unwarp the process. Note this produces an effect which is similar but not equivalent to a full 180 degree field of view fisheye view. If mode is rect, then the warp effect is more of a rectangular extrusion. The script makes use of -fx and therefore will be rather slow.

ARGUMENTS:

osx,dx,isx,iox ... These are the x dimension parameters. osx=output scale factor. osx larger/smaller than 1 magnifies/minifies the area of the result in the output. dx=distortion factor. dx larger/smaller than 1 increases/decreases the distortion. isx=input scale factor. isx larger/smaller than 1 magnifies/minifies the input image in the result. iox=input offset. iox=positive/negative shifts the input to the right/left in the result. Default values are osx=1,dx=1,isx=1,iox=0

osy,dy,isy,ioy ... These are the y dimension parameters. osy=output scale factor. osy larger/smaller than 1 magnifies/minifies the area of the result in the output. dy=distortion factor. dy larger/smaller than 1 increases/decreases the distortion. isy=input scale factor. isy larger/smaller than 1 magnifies/minifies the input image in the result. ioy=input offset. ioy=positive/negative shifts the input to the right/left in the result. Default values are osy=1,dy=1,isy=1,ioy=0

-t ... TYPE is either arcsin or sin. The default is arcsin. When type=arcsin and mode=polar, the image is warped onto a hemisphere.

-m ... MODE is either polar of rect. Mode=polar represents a radial warp. Mode=rect represents a warp in the x and y dimensions. The default is polar. When mode=polar and type=warp, the image will be warped onto a hemisphere.

-f ... FORMAT is either circ or oval. Format applies only to mode=polar. When mode is polar and type is warp, the image will be warped onto a half sphere when format is circ and will be mapped onto a half ellipsoid when format is oval. In the circ case, the hemisphere will nominally have a diameter of the smaller of the width or height of the image. In the oval case the ellipsoid will span the width and height. Format of circ and oval produce the same hemisphere when the image is square. The default is circ.

-v ... VP is the virtual-pixel method to use. Any valid IM virtual-pixel may be used. The default is black.

-c ... VPCOLOR is the virtual-pixel color to use when vp=background. This color is used to fill the sphere where no image shows when mode=polar and type=warp. The default is black.

-b ... BGCOLOR is the color to use to fill the area around the hemisphere when mode=polar and type=warp. The default is black.

This is an adaptation of the technique described at http://local.wasp.uwa.edu.au/~pbourke/projection/lenscorrection/

NOTE: This script will NOT unwarp an image photographed with a 180 degree field of fiew fisheye lens. The fisheye distortion is modeled by a completely different set of equations.

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


Grid Image - Basic Parameters

Original Image

Polar Arcsin Warp
Arguments:
-t arcsin -m polar (default)

Polar Sin Warp
Arguments:
-t sin -m polar

Rectangular Arcsin Warp
Arguments:
-t arcsin -m rect

Rectangular Sin Warp
Arguments:
-t sin -m rect



Checkerboard Image - Basic Parameters

Original Image

Polar Arcsin Warp
Arguments:
-t arcsin -m polar (default)

Polar Sin Warp
Arguments:
-t sin -m polar

Rectangular Arcsin Warp
Arguments:
-t arcsin -m rect

Rectangular Sin Warp
Arguments:
-t sin -m rect



Checkerboard Image - Output Scale And Distortion Parameters

Original Image

Polar Arcsin Warp
Output Scale X
Arguments:
"0.5,1,1,0" -t arcsin -m polar

Polar Arcsin Warp
Output Scale Y
Arguments:
"1,1,1,0 0.5,1,1,0" -t arcsin -m polar

Polar Arcsin Warp
Distortion
Arguments:
"1,2,1,0" -t arcsin -m polar

Polar Arcsin Warp
Distortion
Arguments:
"1,0.5,1,0" -t arcsin -m polar



Checkerboard Image - Input Scale Parameters

Original Image

Polar Arcsin Warp
Input Scale
Arguments:
"1,1,2,0" -t arcsin -m polar

Polar Arcsin Warp
Input Scale
Arguments:
"1,1,0.5,0" -t arcsin -m polar -v black

Polar Arcsin Warp
Input Scale
Arguments:
"1,1,0.5,0" -t arcsin -m polar -v gray



Zelda Image - Output Scale And Distortion Parameters

Original Image

Polar Arcsin Warp
Output Scale
Arguments:
"1.3,1,1,0" -t arcsin -m polar

Polar Arcsin Warp
Output Scale
Arguments:
"0.7,1,1,0" -t arcsin -m polar

Polar Arcsin Warp
Distortion
Arguments:
"1,2,1,0" -t arcsin -m polar



Zelda Image - Input Scale And Input Offset Parameters

Original Image

Polar Arcsin Warp
Input Scale
Arguments:
"1,1,1.3,0" -t arcsin -m polar

Polar Arcsin Warp
Input Scale
Arguments:
"1,1,0.5,0" -t arcsin -m polar -v gray

Polar Arcsin Warp
Y Offset
Arguments:
"1,1,1,0 1,1,1,32" -t arcsin -m polar -v gray



Zelda Image - Background Variations

Original Image

Polar Arcsin Warp
Image Background
Arguments:
"1,1,1,0" -b image

Polar Arcsin Warp
Red Sphere And Yellow Background
Arguments:
"1,1,1,0" -v background -c red -b yellow

Polar Arcsin Warp
Composite Zelda Sphere Onto Checkerboard Background
bubblewarp "1,1,0.5,0" zelda3.jpg tmp.jpg
convert checks.jpg \
\( tmp.jpg -fuzz 1% -transparent black \) \
-composite zelda3_asin_polar_black_checks.jpg

Polar Arcsin Warp
Composite Zelda Sphere Onto Checkerboard Sphere
bubblewarp checks.jpg tmp1.jpg
bubblewarp "1,1,0.5,0" -v gray zelda3.jpg tmp2.jpg
convert tmp1.jpg \
\( tmp2.jpg -fuzz 1% -transparent "rgb(127,127,127)" \) \
-composite zelda3_asin_polar_gray_is0p5_checks.jpg



Zelda Image - Sphere Tiling

Original Image

Polar Arcsin Warp
Arguments:
"1,1,.2,0" -t arcsin -m polar -v tile

Polar Sin Warp
Arguments:
"1,1,.1,0" -t arcsin -m polar



Zelda Image - Sphere Warp and Unwarp

Original Image

Polar Arcsin Warp
bubblewarp -t arcsin -m polar zelda3.jpg zelda3_warp.jpg

Polar Sin Unwarp
bubblewarp -t sin -m polar zelda3_warp.jpg zelda3_warp_unwarp.jpg



Non-Square Image - Sphere Versus Ellipsoid

Original Image

Polar Arcsin Sphere Warp
Arguments:
-t arcsin -m polar format=circ

Polar Sin Unwarp
Arguments:
-t arcsin -m polar format=oval



What the script does is as follows:

  • Applies an arcsin (or sin) warp to an image
  • Uses -fx; therefore slow

This is equivalent to the following IM commands for the case
of an arcsin warp onto a sphere:

  • compute image dimensions and center coordinates, etc
  • ffrx="ffrx=rd?$ipid2*asin(rd)/rd:0;"
  • ffry="ffry=rd?$ipid2*asin(rd)/rd:0;"
  • [ "$dx" != "1" ] && ffrx="ffrx=rd?($ipid2*asin(rd)/rd)^$dx:0;"
  • [ "$dy" != "1" ] && ffry="ffry=rd?($ipid2*asin(rd)/rd)^$dy:0;"
  • convert -monitor $infile -virtual-pixel $vp -background $vc -fx \
    "xd=$sxc*(i-$xc); yd=$syc*(j-$yc); rd=hypot(xd,yd); $ffrx $ffry xs=$isx*$xc*ffrx*xd+$xc+$iox; ys=$isy*$yc*ffry*yd+$yc+$ioy; (rd>1)?$bg:u.p{xs,ys}" \
    $outfile