USAGE: 3Dcover [-s size] [-a angle] [-e exfact] [-w weight] [-t tone]
[-o opacity] [-d diameter] [-r ramp] [-g gamma] [-v vcolor] [-m method]
[-u umbra] [-p penumbra] [-l length] [-b bcolor] [-x xyoffset] [-f fuzzval]
[-H oheight] [-S sharpen] [-P pad] [-sc scolor] [-F fadeval] infile outfile

USAGE: 3Dcover [-h or -help]

-s ... size ....... length of left or right side of cover; pixels or
................... percent of original image; if pixels, the integer>0;
................... if percent then 0<float<100 and % must be included;
................... default=20%; alternately the 3D cover dimensions as
................... TxWxH (Thickness x Width x Height) in any consistent set
................... of units; 3 values must be specified as integers>0
-a ... angle ...... rotation angle in deg; -90<integer<90; default=25;
................... not recommended beyond 60 or -60 when method=ground
-e ... exfact ..... perspective exaggeration factor; 0<float<3;
................... value of 1 is normal perspective; value of 0.5
................... is close to orthographic; default=1
-w ... weight ..... line (stroke) weight for translucent gray join line
................... between front and side; integer>0; default=2
-t ... tone ....... tone (brightness in percent) of join line;
................... 0<=integer<=100; 100 is white; 0 is black; default=100
-o ... opacity .... opacity (percent) of join line; 0<=integer<=100;
................... 0 is transparent and 100 is fully opaque; default=0
-d ... diameter ... diameter of vignette in percent of size of front;
................... integer>=0; default=0 (no vignette); nominal is 100
-r ... ramp ....... ramp (taper) of vignette effect; integer>=0;
................... default=75
-g ... gamma ...... gamma adjustment of vignette; float>0; values less
................... than 1 will lighten/soften the vignette and values
................... less than 1 will darker/harden the vignette;
................... default=0.5
-v ... vcolor ..... vignette color; any valid opaque IM color;
................... default=black
-m ... method ..... shadow method (type); choices are: none (n),
................... backdrop (b) and ground (g); default=none
-u ... umbra ...... graylevel percent value for dark inner part of shadow;
................... 0<=integer<=100; default=50
-p ... penumbra ... extent in pixels of light outer part of shadow;
................... integer>0; default=10 for method=backdrop and
................... default=6 for method=ground
-l ... length ..... length of shadow; for method=backdrop, it is the
................... offset between the cover and the shadow with
................... default=15; for method=ground, it is a factor of
................... the length of the side in perspective and the
................... default=1.5
-b ... bcolor ..... background color; any valid IM color including
................... transparent (none); default=white
-x ... xyoffset ... offset of shadow for method=ground to refine
................... alignment, if needed; comma separate pair of
................... integers; default="0,0"
-f ... fuzzval .... fuzz factor for trimming the front and side
................... perspectives before joining together and trimming
................... the final image; float>=0; default=0
-G ... gravity .... gravity setting for cropping the input image when size
................... is specified as TxWxH; choices are: north (n), east (e),
................... south (s), west (w) and center (c); default=center
-H ... oheight .... desired output height; integer>0; default is the height
................... of the input; if specified, the input image will be
................... resized to this height. The output width will depend
................... upon the oheight value and the amount of rotation angle
................... specified and thus will be smaller than the original or
................... resized width
-S ... sharpen .... sharpening to apply to the (optionally resized) input
................... image; float>=0; default=0
-P ... pad ....... amount of pad to put around the output image using the
................... background color; integer>=0; default=0
-sc ... scolor .... background color; any valid IM color including
................... transparent (none); default=white
-F ... fadevals ... spine fade to gray values; comma separated pair of
................... integers between 0 and 100; The first value is the front
................... value and the second is the back value; 0 is black
................... and 100 is no fade; default="100,100" (no fade)

PURPOSE: To wrap an image around the front and left or right side of box viewed in rotated perspective.

DESCRIPTION: 3DCOVER wraps an image around the front and left or right side of box viewed in rotated perspective. The box size will be proportional to the dimensions of the two sides. Optionally, the box cover may have a vignette effect shown on the front face and a translucent gray line may be drawn on the join between the two faces. Two kinds of shadows may be cast; either a backdrop or ground shadow. The box may be rotated either direction and its perspective exaggeration controlled.

ARGUMENTS:

-s size ... size is the length of left or right side of the cover. Values are either pixels or percent of the width of the original image. If in pixels, then values are integers>0. If percent, then values are 0<floats<100 with a trailing % and no spaces. The default=20%. Alternately, the 3D cover dimensions as TxWxH (Thickness x Width x Height) in any consistent set of units; 3 values must be specified as integers>0. If the height to width aspect ratio of the image (Height/Width) does not match that of the specified units H/(T+W), then the image will be center cropped to match.

-a angle ... ANGLE is the box rotation angle in degrees. Values are -90<integers<90. The default=25. Note that it is not recommended to go beyond 60 or -60, when method=ground. The (pseudo-)shadow will not look right and may be misplaced. Note, if angle is within 2 degrees of zero, it will be converted to 0.

-e exfact ... EXFACT is the perspective exaggeration factor. Values are 0<floats<3. A value of 1 is normal perspective and a value of 0.5 is close to orthographic. The default=1.

-w weight ... WEIHGT is the line (stroke) weight for a translucent gray join line between the front and side faces. Values are integers>0. The default=2.

-t tone ... TONE is the brightness in percent of the join line. Values are 0<=integers<=100. A value of 100 is white and a value of 0 is black. The default=100 (white).

-o opacity ... OPACITY of the join line in percent. Values are 0<=integers<=100. A value of 0 is transparent and a value of 100 is fully opaque. The default=0 indicates no join line.

-d diameter ... DIAMETER of the vignette effect in percent of the size of the front face. The vignette is only applied to the front face. Values are integers>=0. The default=0 indicates no vignette. The nominal value is 100.

-r ramp ... RAMP is the taper or roll-off of the vignette effect. Values are integers>=0. The default=75.

-g gamma... GAMMA is the gamma adjustment of vignette. Values are floats>0. Values less than 1 will lighten/soften the vignette and values less than 1 will darker/harden the vignette. The default=0.5.

-v vcolor ... VCOLOR is the vignette color. Any valid opaque IM color is allowed. The default=black.

-m method ... METHOD is theshadow method (type). The choices are: none (n), backdrop (b) and ground (g). The default=none.

-u umbra ... UMBRA is the graylevel percent value for the dark inner part of the shadow. Values are 0<=integers<=100. The default=50.

-p penumbra ... PENUMBRA is the extent in pixels of the light outer part of of the shadow. Values are integers>0. The default=10 for method=backdrop and the default=6 for method=ground.

-l length ... LENGTH of the shadow. For method=backdrop, it is the offset between the box and the shadow with values as integers>0 and a default=15. For method=ground, it is a factor of the length of the side in perspective with values as floats>0 and the default=1.5.

-b bcolor ... BCOLOR is the background color. Any valid IM color including transparent or none is allowed. The default=white.

-x xyoffset ... XYOFFSET is an offset correction for the shadow for \ method=ground to refine its alignment, if needed. Values are a comma separate pair of integers. The default="0,0".

-f fuzzval ... FUZZVAL is the fuzz factor for trimming the front and side perspectives images before joining them together. Values are floats>=0. The default=0. Typically, this should not be needed.

-G gravity ... GRAVITY setting for cropping the input image when size is specified as TxWxH. The choices are: north (n), east (e), south (s), west (w) and center (c). The default=center.

-H oheight ... OHEIGHT is the desired output height. Values are integers>0. The default is the height of the input. If specified, the input image will be resized to this height. The output width will depend upon the oheight value and the amount of rotation angle specified and thus will be smaller than the original or resized width.

-S sharpen ... SHARPEN is the sharpening sigma to apply to the (optionally resized) input image. Values are floats>=0. The default=0.

-P pad ... PAD is the amount of padding to put around the output image using the background color. Values are integers>=0. The default=0.

-sc scolor ... SCOLOR is the optional spine color. It overrides using image texture for the spine. Any valid opaque IM color is allowed. The default is image texture for the spine. If scolor is specified, then the spine will be that color and the whole image will be on the front face.

-F fadevals ... FADEVALS is the spine fade to gray values. This is a comma separated pair of integers between 0 and 100. The first value is the front value and the second is the back value. 0 is black and 100 is no fade. The default="100,100" (no fade).

REQUIREMENTS: This script requires my 3Drotate script to function.

NOTE: For mode=ground, the ground shadow works between IM 6.6.0.10 and 6.7.2.0; is unknow between 6.7.2.1 and 6.7.2.9; fails for between 6.7.2.10 and 6.7.6.9; works again from 6.7.6.10 to 6.8.3.4; fails again from 6.8.3.5 to 6.8.3.9; then works again starting after 6.8.3.9. The shadow will be slightly different and there will be extra white space on the shadow side, which can be removed using the -f fuzzval argument for versions after 6.8.3.9.

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.