PHP Classes

File: SoftMoon.Rainbow-Maker_instructions.htm

Recommend this page to a friend!
  Classes of Joseph   Rainbow Maker   SoftMoon.Rainbow-Maker_instructions.htm   Download  
File: SoftMoon.Rainbow-Maker_instructions.htm
Role: Documentation
Content type: text/plain
Description: how to use this package
Class: Rainbow Maker
Create transparent gradient images
Author: By
Last change: added instructions for anti-alias effects

removed improper intra-website links
Date: 11 years ago
Size: 23,435 bytes


Class file image Download
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ""> <html xmlns="" xml:lang="en" lang="en"> <head> <title>PHP_Rainbow-Maker Instructions from SoftMoon WebWare: Custom Website Software Development for the 21st Century</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <meta name="generator" content="tsWebEditor ( -" /> <meta name="generator" content="tsWebEditor (" /> <style type="text/css"> body, div, h1, h2, h4, img, ul, li, a { margin: 0; padding: 0; } body { min-width: 800px; font-family: Times, "Times New Roman", serif; color: #000000; background: #FFDEAD url(images/SoftMoon.repeat-y.png) repeat-y; } #top { position: relative; height: 700px; min-height: 42em; min-width: 57em; background: #FFDEAD url(images/SoftMoon.repeat-x.png) repeat-x; } #top, #content, #footer { opacity: .62; -moz-opacity: .62; filter: alpha(opacity=62); } #logo { position: absolute; top: 2.618em; left: 1em; font-size: 1.618em; /*for alt text*/ font-weight: bold; line-height: 150%; } #top h1, #top h2 { font-size: 1.618em; font-weight: bold; } #top h1 { font-family: "Cooper Black", serif; padding: .618em 0 0 1em; } #top h2 { position: absolute; bottom: 17px; left: 0px; text-align: center; width: 100%; } #top h2 span.motto { display: block; font-style: oblique; } #top h2 span em { text-transform: uppercase; font-weight: bold } #top li.current { font-weight: bold; font-style: oblique; position: relative; /*Safari, Google, and Opera all fail to render this at all */ right: 3.618em; } #content { min-width: 57em; width: 100%; /* fix MS and IE: crash 'n' trash (yet another "hasLayout" bug?) */ background: #FFDEAD; text-align: center; } #content h2 { margin-top: 2em; } #content p { text-align: justify; text-indent: -.618em; font-size: 1.236em; width: 27em; margin: 0 auto 0 auto; padding: 0 1em 1em 1em; } #content p:first-letter { font-size: 1.618em; font-weight: bold; color: #000040; } #content #noteConstruction { font-size: 1em; } #content code, #content a { white-space: nowrap; font-size: 1em; } #footer { position: relative; min-width: 57em; height: 100px; background: #FFDEAD url(images/SoftMoon.footer.back.png) repeat-x bottom; } #footer p { position: absolute; left: 1.618em; bottom: .618em; font-size: .78em; font-weight: bold; } span.numerance { font-size: .618em; vertical-align: .618em; line-height: 100%; } .macronym { display: inline; font-size: .763924em; vertical-align: .236076em; line-height: 100%; } acronym.macronym { font-size: .382em; vertical-align: 1.1618em; border-bottom: none; } </style> <!--[if IE]> <style type="text/css"> #top li { display: inline; } </style> <![endif]--> </head> <body> <div id='top'> <h1>Custom Website Software Development for the 21<span class='numerance'>st</span> Century<acronym class='macronym' title="service mark">SM</acronym></h1> <img id='logo' src="images/SoftMoon.gif" alt="SoftMoon WebWare" /> <h2><acronym>PHP</acronym>, JavaScript<span class='macronym'>&trade;</span>, <acronym>AJAX</acronym>, <acronym>XHTML</acronym>, &amp; <acronym>CSS</acronym>: <span class='motto'>We do it <em>all</em> &mdash; We do it <em>right</em></span></h2> </div> <div id='content'> <p>SoftMoon WebWare has developed some useful <acronym>PHP</acronym> and JavaScript<span class='macronym'>&trade;</span> functions, along with a stand alone utility, that we want to share with other developers.&nbsp; We believe in supporting the &ldquo;Open Source / Free Software Philosophy&rdquo; movement to the greatest extent possible, in an effort to make the web a better place for all who visit and utilize it.&nbsp; If you find any of the source code found through this page to be useful to your project, please feel free to include them under the international terms of <a href="" target='page2'>The Free Software Definition</a>, and all the software source code found on this site is released under the <a href="" target='page2'>GNU GENERAL PUBLIC LICENSE</a> terms.</p> <h2>SoftMoon&rsquo;s Rainbow-Maker and the <acronym>PHP</acronym> Rainbow Class</h2> <p>First lets make a few things clear to all.&nbsp; The Rainbow Class is a composite of several files, from the base RGBaa Class to the RainbowGradient Class to the RainbowSculptor Class to the RainbowBuilder Class, with each one extending the previous.&nbsp; The RGBaa Class gives basic <acronym>RGB</acronym> support with an additional 2 channels for transparency.&nbsp; It can take a color defined by name, hex (as used in CSS files), string-based comma-separated decimal <acronym>RGB</acronym> or <acronym>CMYK</acronym> (i.e. &quot;255,255,255&quot; or &quot;100,100,100,100&quot;), or array-based <acronym>RGB</acronym> or <acronym>CMYK</acronym>, and return the appropriate R, G, and B values (from 0-255 each) plus the two alpha-channels.&nbsp; The RainbowGradient Class creates gradient data from the user-given colors; it can apply that color to an image in a limited, linear fashion.&nbsp; The RainbowSculptor Class can sculpt (&iexcl;not simply cut!) the gradient into all the various different shapes.&nbsp; The RainbowBuilder Class adds graphic-file integration.</p> <p>You can download the source files for the Rainbow Maker package from here:&nbsp; <a href=''>rainbow-maker.7z</a>&nbsp; or&nbsp; <a href=''>rainbow-maker.tar.gz</a>.&nbsp; You can try out the Rainbow Maker User Interface here: <a href=''></a></p> <h2>Using the Rainbow Class with rainbowmaker.php</h2> <p>The Rainbow Class was designed to be a stand-alone supplement to the <acronym>PHP</acronym> GD package, but the HTML form generated and processed by rainbowmaker.php is an easy-to-use human interface designed to help the casual user make the most of this powerful and complex software.</p> <p>The Rainbow Class has limited input-data verification, and yet requires tightly configured and/or restricted &amp; limited values.&nbsp; The JavaScript<span class='macronym'>&trade;</span> incorporated into the rainbowmaker.php HTML form will guide the user into proper input values.&nbsp; When using this form, pay close attention that every <i>active</i> form input field has a value typed in, with a few exceptions: if the field is one that automatically pops up a new field (&ldquo;pie slices,&rdquo; background and foreground images) it may be left blank.&nbsp; Only fields that are relevant to your selections will be active.&nbsp; Don&rsquo;t overlook the &ldquo;width&rdquo; field associated with each color when choosing linear gradient shapes.&nbsp; The JavaScript<span class='macronym'>&trade;</span> will restrict you from entering improper characters, as well as out-of-range numerical values; any out-of-range values will be altered to fit the legal range.&nbsp; However, with some browsers, pressing the &lt;enter&gt; key while typing into a form field will submit that form without a final JavaScript<span class='macronym'>&trade;</span> check on the value you typed into that specific field.&nbsp; There is currently no &ldquo;final&rdquo; check on the form field values by JavaScript<span class='macronym'>&trade;</span>.</p> <p>The color specifications are one exception.&nbsp; If a valid color is entered by the user, a &ldquo;color swatch&rdquo; shows that color next to the input box.&nbsp; However, invalid entries are not corrected, as are the other numerical values you may enter.</p> <p>Any errors in data that are either found by the Rainbow Class itself, or that generate a <acronym>PHP</acronym> error, will be caught and reported by the rainbowmaker.php form-processor, and will not &ldquo;crash&rdquo; the program.&nbsp; The data that you entered will not be lost.&nbsp; There <i>should</i> never be &ldquo;true&rdquo; PHP errors or class-specific errors, as long as the JavaScript<span class='macronym'>&trade;</span> is allowed to do its job and you enter valid colors; if you can document such an error, please contact me at:<br /></p> <p>Choose the shape you want filled with the rainbow gradient from the list at the top-left of the HTML form. This is the primary graphic.&nbsp; There are also &ldquo;supergraphic&rdquo; options that you can choose, that take the primary shape you choose and repeats it circularly in many different ways.&nbsp; These &ldquo;supergraphic&rdquo; choices can be found just under the section of the form labeled &ldquo;apply colorband.&rdquo;&nbsp; The shape &ldquo;linear/block&rdquo; cannot be used with these &ldquo;supergraphic&rdquo; choices.</p> <p>Most shapes are filled radially, that is, from a centerpoint to the edge of the shape.&nbsp; Unlike other graphic creation software, the Rainbow Class is designed to fill the shape with the gradient right to the edge all the way around.&nbsp; Other software creates a circular or elliptical gradient, then &ldquo;cuts out&rdquo; the desired shape from this circular gradient.&nbsp; Some shapes generated by the Rainbow Class are filled with a linear or &ldquo;fountain&rdquo; gradient.&nbsp; The first shape listed (linear/block) is the most simple and fastest, creating a linear gradient of varying widths; but it only rotates &ldquo;correctly&rdquo; in multiples of 90&deg;.&nbsp; The shape &ldquo;basic block&rdquo; produces the same shape as &ldquo;linear/block,&rdquo; but uses a different algorithm and therefore can rotate at any angle, however at a loss of speed.&nbsp; While using the rainbowmaker.php on a desktop setup with a local private server this loss of speed is inconsequential, but on a public server it can mean a lot.&nbsp; If the Rainbow Class is being used programmatically to generate an image in real-time (for a web page &ndash; see the next section below) the difference between these two seemingly identical shapes can become critical.</p> <p>The different shapes take different data sets, and as mentioned above, the JavaScript<span class='macronym'>&trade;</span> will activate only the fields you need to fill in for the given shape.&nbsp; Also, different options may require additional data.&nbsp; Many form fields have &ldquo;pop-ups&rdquo; (in red) that offer a simple description of the field or other help. Most options &ldquo;should&rdquo; become self evident with a little experimentation if not obvious from the beginning. Some of the finer points are elaborated on below.</p> <p>First let&rsquo;s get to the heart of shape generation: the rainbow color gradient.&nbsp; The gradient is specified by the &ldquo;base&rdquo; colors involved and the number of pixels between each base color.&nbsp; Each pixel will progress though the gradient.&nbsp; The overall size of the chosen shape will depend on this gradient, and the total number of pixels in it.&nbsp; For radially filled shapes, the longest radius will be the same number of pixels as the gradient (excepting the use of user masks and also possibly involved with custom user shapes; more on that below).&nbsp; Adjusting the &ldquo;master scale&rdquo; will automatically change the size of the created gradient, and therefore of the generated shape. </p> <p>The shapes can be &ldquo;scrunched&rdquo; (not stretched!) using the height/width ratio (the height &divide; the width).&nbsp; A ratio greater than 1 means the height is greater, and the width gets &ldquo;scrunched,&rdquo; while a value less than 1 yields the opposite effect.&nbsp; &ldquo;Stretching&rdquo; the shape could &ldquo;strain&rdquo; the color gradient and create &ldquo;banding&rdquo; of the colors, so ideally the longest radius (from the centerpoint to a point on the shape&rsquo;s edge) will match the length of the colorband.</p> <p>Using the &ldquo;rotate&rdquo; options is fairly straightforward, with the following notes.&nbsp; Rotating the graphic will rotate the height/width ratio scrunch effect, and the rest of the details with it.&nbsp; Rotating aspects of the shape itself (i.e. points, slices, spiral), however, rotates the shape <i>within</i> the scrunched height/width ratio.&nbsp; By combining these three values you can create a &ldquo;skew&rdquo; effect.&nbsp; For example, create a 7-point star (from a gradient of about 100 pixels total so you can easily see the effect), give it a height/width (h/w) ratio of about 62%, rotate the graphic 30&deg; (this is clockwise), and rotate the points -30&deg; (counterclockwise).&nbsp; You will have a star with a point pointing up, skewed diagonally.&nbsp; If the h/w ratio is 1, no effect is seen.</p> <p>Extending the colorband by reflection or repetition brings the rainbow gradient outside of the basic shape. The &ldquo;core&rdquo; shape will be filled the same way and be sized the same, although the overall effect may appear quite bigger. However, if you choose to size the generated image to the shape (see below) it will only be sized to this &ldquo;core&rdquo; size; you must adjust the margins manually (or fit to a larger background) to capture the colorband extension effects in full.</p> <p>Any radially filled shape may be &ldquo;cut&rdquo; into &ldquo;pie slices.&rdquo;&nbsp; These slices may be defined by their start-stop angles in degrees, or by slice number of a specified total number of equal-sized slices.&nbsp; When you define a pie slice, a new set of blank fields pops up automatically.&nbsp; You may leave these blank or use them for another slice.&nbsp; I tried to make this form as easy to use by the mathematically challenged as possible. So for example, you may create a 6-point star with pie slices 2, 4, and 6, of 6 total, and you will have only those 3 points showing, no need to calculate how many degrees per point and where each point slice starts and stops. Then take that generated graphic and use it as the background (see below), apply the same rainbow colorband in reverse (or create a new one of the same number (or even a different number and adjust the point-depth accordingly) of pixels), select pie slices 1, 3, and 5, of 6 total, and whah-la!&nbsp; You have a nice 6-point star with alternating points, and you never had to calculate anything.</p> <p>By &ldquo;squishing&rdquo; the pie slices to match the h/w ratio, the slices come out more &ldquo;even.&rdquo; A slice of a perfect circle from 0-45 degrees is 1/8 of the total, but of an ellipse is not (try it to see why).</p> <p>The &ldquo;supergraphic&rdquo; options take the given shape and repeat it in a circle or ellipse.&nbsp; The circle is broken into sectors (pie slices) and each sector gets filled with a shape.&nbsp; For Nova, Supernova, Nebulae and Quasars, the shape is sized and squished to fit the sector which makes it seem to burst forth from and wrap around the centerpoint of the supergraphic. For Hubs, Wheels, Spokes, and Fans, the shape is not distorted, and the supergraphic will be sized to allow each graphic element to fit inside a sector; but if you bring the graphic elements closer to the center by making the offset negative they may naturally reach into adjacent sectors.&nbsp; If the colorband is extended, it will act differently with these different supergraphics.&nbsp; For Nova and Spokes, the edge of a sector is a border that each shape and its extended colorband will never cross.&nbsp; For Supernova, Nebulae, and Quasars, the colorband can extend into the other sectors and are really only useful with extended colorbands.&nbsp; With Supernova and Wheels, the shape within its home sector is given precedence.&nbsp; If a pixel is not set by that shape, an extension of the colorband from another sector may set that pixel&rsquo;s color, with precedence given to the closest sectors.&nbsp; Nebulae, similar to Supernova, are only useful when the rainbow gradient contains transparencies and the colorband is extended.&nbsp; Any transparency shows though to any extended colorband from another sector.&nbsp; Quasars and Fans &ldquo;overlap&rdquo; the extended colorband (either clockwise or counterclockwise), but no transparencies show through to other extended colorbands; and like Nova and Supernova, transparencies show through to the background.</p> <p>One of the defining aspects of the Rainbow Class is its abilities with transparency gradients.&nbsp; For each pixel you may have a color defined by <acronym>RGB</acronym> channels plus <b>2</b> (<b>two</b>) transparency channels.&nbsp; These two transparency channels are independent of each other.&nbsp; One transparency channel is used to blend the rainbow gradient&rsquo;s color into the background, while the other defines the final transparency of the pixel (after it is mixed with the background, if it is mixed at all).&nbsp; You may even specify a &ldquo;rainbow&rdquo; with no color and only a final transparency gradient, then apply that to a given background image as a given shape.&nbsp; For example, you can take a given picture and impose a star-shaped transparency on a portion, then (if saved as a .png file) you can use that image as a floating mask over another (maybe in a web page somewhere), with the underlying image showing though the star-shape.</p> <p>To create an anti-alias effect at the edges of your created shape, simple repeat the last color for 1 to 3 pixels (experiment with the number to obtain the best results, depending on the shape you're creating) and turn on the transparency option.&nbsp; This transparency should progress &ndash;to&ndash; about 80%-90% at the final pixel.&nbsp; You would therefore normally use a transparency gradient from 0% to 90%; but if your shape&rsquo;s gradient already has a transparent value in the last color, you would adjust the values (of the anti-alias pixels) accordingly.</p> <h2>Using the Rainbow Class with your own project</h2> <p>The first step to using the Rainbow Class is to get to know it with rainbowmaker.php.&nbsp; Once you understand what it can do, and perhaps even what you want it to do in terms of what gradient-filled shape you want to create, you&rsquo;re ready to use the Class with your own <acronym>PHP</acronym> script.</p> <p>The Rainbow Class was developed with the idea that static-sized graphics in web pages do not re-size in the same detail on different browsers, and in fact some browsers do quite a poor job, while others do a fairly good job.&nbsp; WebKit based browsers (Apple&rsquo;s<span class='macronym'>&reg;</span> Safari<span class='macronym'>&trade;</span> and Google&rsquo;s<span class='macronym'>&reg;</span> Chrome<span class='macronym'>&trade;</span>) do a nice job; a graphic containing fancy text may look OK if these browsers re-size it.&nbsp; Internet Exploder, however, creates grainy images when re-sized.</p> <p>The solution to this problem is to use Ajax techniques.&nbsp; With JavaScript<span class='macronym'>&trade;</span> you can find the end-user&rsquo;s screen-width in pixels and report that back to the server.&nbsp; A PHP script can generate a custom-sized graphic with fancy text in full-detail and send that to the end-user&rsquo;s browser.&nbsp; What was missing in this solution was the GD package&rsquo;s ability to create complex gradients and work with transparencies in an advanced way. The Rainbow Class also supplies solutions to complex mathematical problems in tiling the graphic in a circle.&nbsp; This would be virtually impossible to do by taking a given image and copying it into another when the image co-ordinates overlap.</p> <p>Be sure to read the comments throughout the Rainbow Class files.&nbsp; There is plenty of info within describing how to use the methods and the overall Class in general.&nbsp; That info will not be repeated here.</p> <p>The easiest way to use the Rainbow Class is to hack into the rainbowmaker.php file and at the appropriate place (after the instance of the Rainbow Class is created, before a method is called), un-comment the following line:</p> <code>$rainbow-&gt;&iquest;dumpAttributes=TRUE;</code> <p>Then use rainbowmaker.php (in your browser) to create the graphic you want.&nbsp; All the values needed to be passed into the RainbowBuilder Class will be shown with their given IDs.&nbsp; From this you can create custom arrays to pass into the Rainbow Class in your own project, adjusting the proper values in the arrays by a (possibly variable) percentage amount.</p> <p>The Rainbow Class is modular so you can use just what you need.&nbsp; For many of your own projects, the RainbowSculptor Class or even the RainbowGradient Class may be all you need.&nbsp; You may find that you are building a multi-layered image however, and the RainbowBuilder Class will give you tools to do this quite a bit easier.</p> <p>The Rainbow Class will automatically create a GD image resource if you don&rsquo;t give it one to work with.&nbsp; By creating an instance of the Class, you have a reusable tool.&nbsp; Calling a method once will generate a GD image; calling another method or the same one again will use the previously generated GD image.&nbsp; Or you may create an instance (i.e. <code>$Rainbow=New RainbowGradient;</code>), and then before calling a method set the GD image (i.e. <code>$Rainbow-&gt;image=imagecreatetruecolor( ... );</code> or maybe something like <code>$Rainbow-&gt;image=imagecreatefromjpg( ... );</code> or maybe you create something with the GD package and want to add to it using the Rainbow Class by <code>$Rainbow-&gt;image=$myGDhandle;</code> ).</p> <p>Note that if you supply a GD image resource, or when you call a second method (or more) on the same instance, the RainbowBuilder will normally not set the background-color.&nbsp; However, background images and the final transparency value, if any, will be added.&nbsp; Also, most image-sizing options will be ignored (except &ldquo;autosizing to select images&rdquo;); the final image will be the same size as the one passed in - in fact it will be the one passed in, only with the added Rainbow.</p> <p>If you &ldquo;autosize to select images&rdquo; and supply your own GD image resource, the resource will always be &ldquo;sized to&rdquo;, and its {x,y} position will be {0,0}.&nbsp; If any other resource (back/foreground images or the Rainbow itself) is &ldquo;sized to,&rdquo; the Rainbow instance image -may- be re-generated to any required larger size with the passed-in GD resource copied in at the appropriate place, and it will then also receive the specified background color.</p> </div> <div id='footer'> <p>All content found on this site Copyright &copy; 2012 by SoftMoon WebWare, all rights reserved, unless otherwise specifically noted.<br /> <span class='notice'>&ldquo;JavaScript<span class='macronym'>&trade;</span>&rdquo; is a trademark of Sun Microsystems.</span> <span class='notice'>&ldquo;Google<span class='macronym'>&reg;</span>&rdquo; &amp; &ldquo;Chrome<span class='macronym'>&trade;</span>&rdquo; are trademarks of Google, Inc.</span> <span class='notice'>&ldquo;Apple<span class='macronym'>&reg;</span>&rdquo; &amp; &ldquo;Safari<span class='macronym'>&trade;</span>&rdquo; are trademarks of Apple, Inc.</span> </div> </body> </html>