Fred's ImageMagick Scripts: BUBBLEWARP

Fred's ImageMagick Scripts

Licensing:

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.

BUBBLEWARP

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

Download Script

last modified: January 17, 2022

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