Updated Information February 6th 1992 ============================================================== I M A G E M A S T E R for the Amiga ------------------------------------- I M A G E M A S T E R F / C for the Firecracker 24 ------------------------------------------------------ I M A G E P R O F E S S I O N A L for the Amiga & HAM-E ============================================================== Information current to version 7.02 of these programs Author: Ben Williams +-----------------NOTICE-------------------+ | This information is copyright 1992 Black | | Belt Systems, ALL RIGHTS RESERVED under | | the Pan-American Conventions. | +------------------------------------------+ The latest versions of our image processing software have additional functions which are not described in the manual or the current addendum. This document describes those new capabilities. For developers, please note that we have included much more detailed information on the Public Interface; and that the release disk does contain a directory with a complete example of how to write a PI Module using SAS C. Until we formally reprint the manual, additional documentation will be provided in on-disk format, ready for printing on your own printer. We had originally planned to print continual addendums, but there is no way we can keep up with the fast pace of development of this program using something as conventional as paper. We hope you enjoy these additional capabilities! Morphing ======== This is a compose operation. Morphing is the process of combining two images to form a third image, using geometric (positional) and color information from both source images. Usually, it is also taken in general to mean the generation of a sequence of images which provide a continuous (or as nearly so as possible) change from one image to the other. This effect is the basis for many current video and cinematic scenes of startling content. The Morph capability implemented in our image processor provides the abilities to generate individual frames as needed, or a sequence of frames to your specifications. You have excellent control over the two most important factors in the process: 1 - The geometric transform information (positional changes) 2 - The coloremetry transform information (transparency changes) The first, geometric control is provided by the user specifying "control points" on both of the source images. To understand what this means, let's consider a simple example. Say you wish to apply the morph process (we'll simply call this "morph" from now on) to a mans face and a womans face. The images are quite different; the man is swarthy and has a wide, solid face, while the woman is elegantly slim, with high cheekbones and has an oriental cast to her eyes. A good beginning for working on these two images is to start with what the images have in common; what the viewer will "naturally" assume are features that are "the same". Examples of this are eyes, eyebrows, nose, mouth, and ears. For the eyes, you might place control points on the start image at the corners of the eyes. Note that points automatically appear in the same location on the other image. Now, you move the points on the other image so that these points are also in the corners of it's eyes. What you have done is told the image processor that you expect these two locations - the eye corners - to remain "attached" to each other throughout the morph process. You'll continue to apply control points to the pupils of the eyes, across the eyebrows, the lips, the ears, the edges of the face and so on. You may use as few as ten or so points, or you may use several hundred. The more you use, the more precisely controlled the morph effect will be. Note that you can save your control point sets; you should do this often, so as to prevent the loss of your work in case of a system failure of any kind. The best way to learn how to morph is to try a few. We strongly suggest that you start with two faces; and that you keep the initial morphs very small, about 80x50 or 40x25. Morphing is a computationally intensive process, and generating each frame takes considerable time. Here's a hint. When you're experimenting, set the number of frames to 20, and then generate only frame 10. Use a linear transparency curve. This will show you what will occur for a morph that is 50% complete; that is when both images are maximally merged with each other. If you have missed something important, it will likely show more at this time than any other. The morph capability is extremely open-ended; experimentation will produce outstanding results. We have found that you typically need between 50 and 150 control points to create the most effective morph results. Fewer points tend to leave areas "uncontrolled", more result in longer computation times and not much difference in output quality. By all means experiment, though - you may achive effects we did not expect which please you. ---------- List Requester (ARexx-based capability) ======================================= This command allows you to bring up a list requester inside the image processor from which the user can select and entry; once an item is selected, a value (selected by you) is returned to the calling ARexx script or macro. The list environment for the PI Modules is implemented using this capability. For more details, see the information describing the list environment for PI Modules. In particular, see the script "launch.rexx" and the file "list.list" for a complete example of how to use this powerful capability. Here is the format of the ARexx command: 'listreq "Title text",listfilename,"keywords,etc"' ---------- Buffer Management ================= Load Image as Secondary ----------------------- This option will appear when you already have a Primary image buffer, it allows you to load the next image in automatically assigned as the secondary buffer. If buffers besides the primary are already loaded, then you will also be presented with the option to replace an old buffer as secondary. ---------- Load Image as Blend ------------------- This option will appear when you already have a Primary image buffer, it allows you to load the next image in automatically assigned as the blend buffer. If buffers besides the primary are already loaded, then you will also be presented with the option to replace an old buffer as blend. ---------- Load Image as Brush ------------------- This option will appear when you already have a Primary image buffer, it allows you to load the next image in automatically assigned as the brush buffer. If buffers besides the primary are already loaded, then you will also be presented with the option to replace an old buffer as brush. ---------- Co-ordinates ------------ The image processor now provides you with the option of displaying image X and Y co-ordinates while you work in the display. This option is controlled by a button in the Display panel called ``Show Cords''. There is another button that affects the co-ordinates, also in the Display panel. This one is called ``Drag Relative''. If you select it, then the co-ordinate display will show you the size of the object, or the distance of the pointer from the location you started drawing or selecting. This is useful if you need to create a specific size object. You can use the ``Cords at bottom'' button to switch the display from the top right to the bottom right. The ``s'' key will do the same thing when pressed while you are drawing. The following two ARexx commands allow to to set these conditions up: COORDS [showattop] ------------------------- Here, is required, 0 means no, 1 means yes GRID ----------------------------------------- Here, is required and should be 1 for on, 0 for off. If is present, then the other four parameters must also be. and define the spacing of the grid. and define the offset from the top left edge of the image where the first vertice of the grid will occur. These last two parameters MUST be values less than the first two. ---------- Grid ---- The image processor provides a grid capability. This is enabled in the Display panel by the ``Use Grid'' button, and when on, allows you to draw only on the selected grid size. Grid size and position is controlled by two buttons in the Display panel called ``Set Grid Interactive'' and ``Set Grid Numeric''. If you use the interactive mode, you are presented with the main image, and you use the mouse to pull out a rectangle. That rectangle sets both the gird size (the same as the rectangle) and its origin (the same as the rectangles corners). If you use the numeric method, you are prompted for an X and Y size, as well as an X and Y origin. The sizes represent the width and height of each grid cell. The origin represents the distance from the upper left hand corner (0,0) of the image that the first ``snap'' point occurs. ---------- Adding Noise ------------ The function F/x Random Dither allows you to add noise to an image if the region is too smooth for your taste. You can set the amplitude of the noise to your liking. ---------- Clip to exact size (F/x) ------------------------ This capability allows you to specify a rectangular region, for instance 100 by 75, and then clip that exact size region from the primary image. This is useful when you are trying to create a smaller output image from an already existing larger image. ---------- X-Specs Over-Under ------------------ This function takes an image that is interleaved for the X-Specs glasses and modifies that image to the X-Specs Over-Under format, used by some X-Specs viewers. The conversion takes place entirely in the Primary buffer. ---------- X-Specs Interleave ------------------ This function takes an image that is over-under, that is, has one field over the other, and changes it to the interleaved format. The conversion takes place entirely in the Primary buffer. ---------- X-Specs Separate ---------------- This function takes an interleaved X-Specs image in the Primary buffer and separates the two fields into two new buffers. You have the opportunity to name these buffers if you like; if not, they will be called Clip_N and Clip_N+1, where N is the current clip number. Note that this process creates two new buffers which have half the number of lines of the Primary buffer in addition to the Primary buffer, and as a result will require as much additional memory as the Primary buffer consumes. ---------- F/x User Transforms ------------------- This is one of the most flexible, and potentially complicated, operations in the entire image processor. In simple terms, this provides you with a graph, where you have the opportunity to specify the resulting output from every level in a buffer. You can cause this function to create the exact operations for contrast, brightness, gamma, negative, histogram equalization and more. You can save (and reload later, of course) any transform curve you create; several are provided as ``boilerplate'' for you to try out. A special function also sets the transform curve to the current curve of the iamge itself; this can be used to equalize the image. The files that are saved are in a textual format. The file should contain at the beginning the four letters ``TFRM''. Following that first line, you can have one of three things on any line of the file. A blank line, which will be ignored; a line that begins with the ``*'' character, which allows the line to contain any comment; or a number from zero to 255. Only the first 256 lines which contain numbers are read from the file. You can create, or modify, these files with any good text editor (but not a word processor). The curve itself can be drawn with the mouse, smoothed, or as mentioned previously, generated from the image. Note that there is a smaller graph area which contains the current transform curve of the image at the upper left. ---------- Stretch (Scale, Zoom) --------------------- The Stretch Clip operation now has the ability to stretch to a particular percentage, as well as the original stretch to a particular pixel size. ---------- Map to Range ------------ This tool is similar to the Map To Palette capability, except it uses the current range, and (since ranges may be smaller than 256 colors) the range will be automatically interpolated (smoothed) if the range is 255 or less colors. ---------- Black Balance ------------- Black Balance is a tool that re-balances the entire image, based upon a region you specify. The principle underlying Black Balance is the same as that used by Grey and White balance operations. The assumption made is that you can (by observing) locate an area on the image that should have been black. If you can, you identify this area using the region select tools, and the function will re-balance the entire image based upon that information. This is very effective for images that have low contrast or coloration. ---------- Force Dynamic ------------- This operation is similar to the Dynamic Range operation. To understand the difference, we need to look at Dynamic Range. The Dynamic Range operation examines the entire image, finds the darkest and lightest regions, and then linearly expands the contrast and moves the brightness center appropriately. This results in the maximum possible contrast without losing any image information. Force Dynamic does the same thing, except that the examination for maximum and minimum regions is only performed in the region you specify, not the entire image. As a result, Force Dynamic can indeed lose image data. One possible use would be for an image that was contained as a sub- image within another --- for instance, a picture on a television in a larger image. You can use Force Dynamic on the TV image, and that image will be brought to it's best possible contrast (and the rest of the image will be seriously damaged). ---------- X-Specs Conversion ------------------ This operation allows you to create an X-Specs interleave format image from the image in the Primary buffer and the image in the Secondary buffer. You can even do this with dissimilar size images! ---------- Absolute Resample - no anti-aliasing ------------------------------------ The stepped Zoom operation now allows you to reduce an image's resolution without averaging neighboring pixels; this was added so that the automatic expansion of HAM-E images to hi-resolution pixels (with synthesis of intervening pixels using the same method as our advanced Anti-Alias engine) could be reversed without any unwanted smoothing of the image. Suggested use is to use it on the horizontal axis only. ---------- Merge with Render from Range ---------------------------- This operation will take a range of colors you have defined in the palette and render the secondary image into the primary image using only those colors. The operation is similar to a merge, in that the entire secondary image is rendered into the region you specify. For instance, if you have a 4 color range that consists of black, white, and two intermediate grey levels, then that's how the image will be placed into the primary image. This allows you to use unlimited creativity in color compositions. One option is to use dither when rendering using the range colors. Dither effectively increases the available color space, and images will look more accurate, as well as somewhat ``rougher''. Another option is to turn ``Excursion Off'' for the render. This is only effective if dither is on; the effect is to increase the number of colors available in dither, but it will also make the iamge appear even rougher. Another option allows you to select a stretched merge, or a sub- sampled merge. You can use blending in the normal fashion with this operation, also. You should be aware that when blending is on, more colors are using to composite the image, as various levels of the colors in the range are blended with the colors in the primary image. ---------- Additional Render Controls -------------------------- The control "Excursion Off" may now be used to modify the quality of most render modes. Excursion off: This works with dithering to provide a larger color space. If you turn off the dither when rendering, this has no applicability. If you turn excursion off, the dither operations can reach more colors in the color space. The image may appear rougher as a result. We suggest you try things both ways before committing to a final render. All Amiga render modes now have multiple dither choices for your rendering convenience; you may currently choose from: No Dither ------- Uses the nearest color in the palette; contours. EDD ------------- Most color accuracy; roughest image. Heavy dithering Floyd-Steinberg - Best compromise; not too rough, good color accuracy Jarvis ---------- Smooth; color begins to show contouring (banding) Stucki ---------- Extremely smooth; contouring quite evident In addition, all Amiga render modes have been considerably improved as far as output quality goes. ---------- Compose with Logical OR ----------------------- This image composition operation will combine the Secondary image into the Primary image using the logical OR operation. ---------- Compose with Logical AND ------------------------ This image composition operation will combine the Secondary image into the Primary image using the logical AND operation. ---------- Multiple Blend Technique Application ------------------------------------ You can now use any of the three blending techniques in combination with each other. The manual implies that the blending techniques are independant and exclusive. While you can use them independantly, you can also use them together in any combination. ---------- Smooth Edge Blending as a Percentage ------------------------------------ The smooth edge blending capability now has the ability to be specified as a percentage. The specify by number of pixels is still intact, of course. This will help you use the technique on larger images, and also allows you to apply similar looking edge blends without having to re-specify the blend lengths. ---------- Masks ----- The image processor can now save masks with images, contrary to the statement in the manual that it does not. These masks are in a proprietary format readable by the image processor, and will be ignored by other IFF readers. The PMBC Public Interface module will also save and load masks with images. ---------- Color Separations ================= General ------- The image processor now has full RGB, CMY and CMYK color separation capability for both 12 and 24 bit images. The color separation tool is located in the File I/O panel; it is extremely flexible and allows you to save multiple control parameter settings for your various color separation needs. Color separations are positive, and so where you expect a lot of ink to be on the paper, the image on screen will have the most color (``ink''). If you use a color map, the image will be the color of the separation (cyan, for instance) where the paper is white, which is somewhat counter-intuitive, and it will be black where it is maximum cyan. ---------- Under Color Removal ------------------- This control sets the amount of color (cyan, magenta, yellow) ink removed when they can be replaced by black. ---------- Gray Component Replacement -------------------------- This control sets the amount of black ink that replaces what was removed by the Under Color Removal tool. ---------- Magenta Ink Mix Correction -------------------------- This control compensates for impure ink colors, IE, the cyan ink is not pure cyan. The default value is set for Inkum Inks, which we strongly recommend for inkjet use. ---------- Yellow Ink Mix Correction ------------------------- This control compensates for impure ink colors, IE, the magenta ink is not pure magenta. The default value is set for Inkum Inks, which we strongly recommend for inkjet use. ---------- Output 12 Bit ------------- This setting allows you to create 12 bit color separations, needed for some Amiga DTP programs. You should always use 24 bit separations for professional work. ---------- Output 24 Bit ------------- The setting allows you to create 24 bit accurate color separations. ---------- Gray CMAP --------- This section causes a grey CMAP to be placed in the output file, which is required for proper color separation operation. The alternative, Color CMAP, makes the images easier to understand and view, but is not useful for real separations. Color CMAP ---------- This places a color CMAP in the separation file, which will let you visually cue in to how much ink will be used when observing the files. Do not use this settings for final work; You must place a Gray CMAP in the file for it to be useful. ---------- Set To Default -------------- This control forces the Under Color Removal, Gray Component Replacement, Magenta Ink Correct, and Yellow Ink Correct to their respective default values. Set To No Correction -------------------- Just as it says. The colors are created via a straight mathematical transform with no correction for the shortcomings of inks and paper. Generate CMYK Separation ------------------------ This produces four output files, cyan, magenta, yellow and black. This is what you will typically use for professional separations. Generate CMY Separation ----------------------- This produces three output files, cyan, magenta and yellow. This is what you will typically use for three color printer ribbons. Generate RGB Separation ----------------------- This allows you to separate the image into it's respective R, G and B components. We don't know what use it is, but others have this capability, so we added it also. Save Settings ------------- This allows you to save the current settings of the Color Separation panel. This is very useful for situations where you'll be outputting to various print agencies or printers, and the settings are different. Note that if you save a settings file and name it ``Default.csep'', it will be automatically loaded when the software starts. It should be located either in the current directory or drawer (not recommended) or in the s: assignment (highly recommended). ---------- Load Settings ------------- This loads any settings that you saved. ---------- Extensions ---------- You can preset the extensions used on the color separation files if you like using the four text entry fields provided. ---------- Genlocking ========== Creating a Transparent Region ----------------------------- Rendering now allows you to specify Transparency for genlocking by marking a region that you do not want to be transparent. So, if you have drawn a graphic you want to appear in the top right of the frame, just move the object there using the usual tools, then when you render, just define that object as the ``non-transparent'' region. The entire remaining portion of the image will be drawn using the Amiga (or HAM-E) ``color zero'', which will make it transparent for genlocking purposes. Keep in mind that not using the color zero color can substantially reduce the render quality of an image, especially when you are using fewer colors. ---------- Color-Keying: Transparency by Color ----------------------------------- You can also create a genlock (transparent) region by selecting the Color Gen Mask button. This will cause the image to have transparent (genlock) areas wherever the color in the image matches the color selected in the process panel using ``define color''. The color radius also affects the genlock area generation. An example would be where you have a picture of a model you have taken against an aqua background. Select the aqua area as the ``defined color'', and then use Color Gen Mask to build the genlocked image. The image will be transparent everywhere but where the model is. Of course, if the model is wearing any aqua color, or has aqua eyes, that region will be transparent as well. You can fix this up by changing the colors of that region using the paint tools. Keep in mind that not using the color zero color can substantialy reduce the render quality of an image, especially when you are using fewer colors. ---------- Creating Non-transparent Renders -------------------------------- If you want a render to be totally non-transparent (that is, doesn't use the Amiga color zero anywhere), then select the ``Identify the genlock non-transparent area'' button an choose "entire image" as the region. The entire image will be non-transparent. Keep in mind that not using the color zero color can substantialy reduce the render quality of an image, especially when you are using fewer colors. ---------- DCTV ==== Filtering --------- The DCTV library allows you to filter the RGB image that is used to create the final DCTV image. If you select the ``Use DCTV RGB Filter'' button when you render DCTV images, this filter is called into action. Again, this function is entirely dependant upon the code in the DCTV.library software, and Black Belt Systems is not responsible for any image degradation you may experience in the final DCTV image. ---------- Brushes ======= Transparent Brush Cutting ------------------------- When you select Cut Out New Brush, you will now get a two button panel that asks you if you'd like to do this as a transparent operation or just as a solid area. If you do select transparency, the transparent portion of the cut will occur where the background color (See Color Definition, next) is similar to the color in the cut region. The color radius affects the transparent region calculations. ---------- Color Definition ================ Adjust Foreground Color ----------------------- This new option within the paint panel allows you to immediately adjust the foreground color using RGB controls. ---------- Sample to Foreground Color -------------------------- This new option within the paint panel allows you to immediately adjust the foreground color by selecting a region on the Primary image. ---------- Adjust Background Color ----------------------- This new option within the paint panel allows you to immediately adjust the background color using RGB controls. ---------- Sample to Background Color -------------------------- This new option within the paint panel allows you to immediately adjust the background color by selecting a region on the Primary image. ---------- Palette Mapping --------------- In the main paint panel there is a new option called "Palette Mapping". This function is for artists who wish to change colors which have already been painted with, from the palette or from a range. To do this:- (1) Copy the range that you have drawn with into the current palette, (2) Choose "Palette Mapping" and "Establish Map", you will then be able to select the area to be affected, (3) Adjust the colors in the palette to the new colors you want, (4) Choose "Palette Mapping" and "Apply Palette Changes"; This will change the drawn colors in the image in the same way you changed the palette colors. Note that the "Establish Map" function only works on colors that exactly match those in the palette. Also, "Toss Map" can be used to free up some memory after you have finished Palette Mapping. ---------- Paint Settings To Disk ---------------------- In the Paint Panel are Load and Save Paint Settings buttons. This saves all the settings you are then using to paint with including the foreground and background colors. ---------- Filling ======= Brush Emboss ------------ This fill mode will emboss the image with a pattern derived from the brightness of the current brush. The fill proceeds in a regular rectangular fashion. ---------- Brush Brick Emboss ------------------ This fill mode is similar to Brush Emboss, but every other line of repeated brush patterns is offset by 1/2 the brush width, resulting in a fill that has the 50% offset characteristic of brick architecture. ---------- Poly-range Fills ---------------- Polyrange fills are a new and unusual type of fill developed by Black Belt specifically for our image processing software. The best way to describe a polyrange is to begin with a polygon. Let's take a polygon in the form of a triangle as our example. A triangle has three points. What polyfill will do is assign a color to each of those points from the range you supply, assuming only that the range you supply has three points. So, if you have a range that is red, green, blue, yellow... etc, then the triangle will have red, green and blue assigned to the three points of the corners. Now, there are two different ways that polyranges will work, depending on the Smooth Range fill setting. If smooth range fill is off, then the pixels inside the triangle will be filled according to the vertex (point) they are nearest to. So, pixels near the red vertex will also be red, and so on. If smooth range fill is on, then the pixels inside the triangle will be filled with all three colors, proportionally to how near they are to that particular vertex. So, for pixels right at the red vertex, you get red. For one halfway between red and green, but far away from blue, you'll get a yellow color. Keep in mind that polyranges can work with any number of points, so you can make some really spectacular fills. Note that large numbers of vertexes will cause long computation times, however. Rectangles and full screen polyrange fills act like four vertex polygons, and so require a four color range. If you have less colors in the range than there are vetexes in the polygon, then the range will repeat along the vertexes untill all vertexes are assigned a color. ---------- Freehand and Elliptical Polyranges ---------------------------------- We've done something wild, here. Since a freehand area or an ellipse are not composed of vertexes as polygons, polyarcs, rectangles and so on are, we needed a new way to apply polyranges to them. What we do is find out the length of the edge of the freehand area or ellipse, and the we distribute the entire range of colors around the perimeter of the region. Let's say you have a 6 color range (you might want to try this, the results are stunning!) or Red, Yellow, Green, Aqua, Blue, Purple. These colors are placed at points equidistant from each other around the perimiter of the object. So, if you draw a very round ellipse, with smooth range on, you get a gorgeous ``color wheel''. Freehand areas provide very strange and beautiful results. Again, be careful not to use ranges with very many colors unless you are prepared to wait a long time. ---------- Dual Range Fills ---------------- The image processor now provides for a new type of fill that uses two separate color ranges to derive fill colors. These can be utilized once you have selected two ranges; you can select both from the paint panel, the new button to pick the secondary range is called ``Select Second Range''. Once you have picked the two ranges, you can use the following fill tools: ---------- Dual Horizontal Range --------------------- This fill mode places the two ranges above, and below the region to be filled. The pixels in the filled area are derived as a function of the distance between the top range, and the bottom range; they change horizontally across the filled region as they utilize different pixels from the two adjacent ranges. ---------- Dual Vertical Range ------------------- This fill mode places the two ranges left, and to the right of the region to be filled. The pixels in the filled area are derived as a function of the distance between the left range, and the right range; they change vertically across the filled region as they utilize different pixels from the two adjacent ranges. ---------- Dual Horizontal Warp Range -------------------------- This fill mode places the two ranges above, and below the region to be filled. The pixels in the filled area are derived as a function of the distance between the top range, and the bottom range; they change horizontally across the filled region as they utilize different pixels from the two adjacent ranges. The ranges are ``pinched'' together near the edges of the filled region. ---------- Dual Vertical Warp Range ------------------------ This fill mode places the two ranges left, and to the right of the region to be filled. The pixels in the filled area are derived as a function of the distance between the left range, and the right range; they change vertically across the filled region as they utilize different pixels from the two adjacent ranges. The ranges are ``pinched'' together near the edges of the filled region. ---------- Dual Range Example ------------------ You need to create two different ranges. You can use as few as two colors in the first range, and five in the second range. You're going to be using the "Smooth Range" modifier, so you'll get a beautiful spread of colors anyway. Make the first range all dark blue. That's right, NO color change in the range. Make the second range go from aqua to orange to aqua. That's easy to do, just set one end of the range of colors to orange, one to aqua, and choose mirror range. From the palette display, select the aqua-orange-aqua range and place this in the range panel. Return to the palette, and then place the Blue-Blue range in the range panel. Since the Blue-Blue is the last range you entered, it is the current range. Now, exit back to the paint panel. Here, select the Second range (the aqua-orange-aqua one) using the control provided for that purpose. Go into the Fill panel, select "Smooth Range" and also select the fill mode as "Dual Horizonal Range". In this context, "Horizontal" means the way that the range lies on the image - NOT the way that the fill occurs. Here is how the fill will work: Top of fill Range 1 Blue <----------------------> Blue ^ ^ ^ | | | | | | Filled area where color | | | <-- changes smoothly between | | | the two adjacent ranges | | | v v v Range 2 Aqua <-------Orange---------> Aqua Bottom of fill You're ready to try the fill itself now. Select a rectangular region and fill it, or do the entire image if you'd like. You should have blue at the top, and this should fade down to an orange glow in the middle where the sun has just dissapeared. ---------- Any Angle Range Fill -------------------- This powerful new fill mode consists of an angle entry field and a mode button in the fill modes panel. You can specify any possible angle, either positive or negative. ---------- Buffer Operations ================= DPI operations -------------- There are several operations that work within the concept of "Dots- Per-Inch". One is accessed in the Buffer panel; it allows you to "Set Current DPI and Size" for a buffer. For instance, you can say, this buffer is 8.5x11, or that it is 200 DPI. There is an operation in the F/x panel that allows you to rescale using DPI as the criteria. You may find this particularly useful if you are into printed graphics. ---------- Initialize to Color ------------------- This brings up the RGB panel and allows you to create the buffer filled with a specific color. ---------- Setup Panel =========== There is now a setup button in the image processor that provides you with the ability to specify Interlace or Non-interlace when the program starts. ---------- Information =========== Other Buffers ------------- This tool allows you to obtain X:Y pixel information, total memory used, parent, and other information about any buffer in the system. ---------- Display ======= Fast HAM draw mode ------------------ This display mode uses a pre-calculated palette for fast drawing. Future updates of the image processing software will concentrate on improving the speed of this tool; it will be the very first to be re- coded into assembly language. ---------- ARexx ===== Port Names ---------- Here's something we inadvertantly left out of the manual... the port names for the ARexx ports in Imagemaster, Imagemaster F/c, and Image Professional. Here they are: IM_Port For both IM and IM F/c. IP_Port For Image Professional. ---------- render command changed ---------------------- On page 177 of the manual, the parameters given are not complete. Parameter number six , described on page 178 (correctly), is missing. Make sure you take this into account if you are using the render command. Here is the correct command string: render [cols] ---------- filerequest command changed --------------------------- This command now returns the string 'FR_CANCELLED' if the user cancels the file requester. This allows you to abort operations in progress. ---------- newbuf (changed) ---------------- The newbuf command now has the following syntax: newbuf [name] [MASK] The new keyword MASK allows you to specify a new buffer with a local mask plane available. This is required if you are writing a PI Load module that will need a local mask (for a non-rectangular image). Note that there are two optional parameters here; you'll need to provide a NULL string for the "name" parameter if you want the automatic naming to work, as in the following example: 'newbuf "'||width||'","'||height||'","","MASK"'; ---------- Firecracker-specific manipulation (new commands) ------------------------------------------------ The ARexx commands FCHIDE and FCSHOW have been added; these turn the FC24 display on and off. They have no effect (and cause no error) in the other versions of the image processor. ---------- Finding the mouse location from ARexx (new command) --------------------------------------------------- The ARexx command "WHEREMOUSE" returns the mouse's current co- ordinates using the image resolution. ---------- coords (new command) --------------------------------- This allows you to turn the co-ordinate facility on and off from ARexx, and also to control the placement of them. If show is 1, then co-ordinates are on. If 0, then they are off. If top is 0, then the co-ordinates are displayed at the top of the screen. If 1, then at the bottom. ---------- grid (new command) ----------------------------------------------------- This command allows you to set a particular grid. When on is 0, the grid is off. When 1, grid is on. xgrid and ygrid allow you to set the spacing between grid lines; xoff and yoff allow you to set any offset from the top left corner (0,0) of the image. ---------- newasprimary (new command) -------------------------- This is similar to the newbuf ARexx command, except that the buffer it creates is always the primary buffer. The newbuf command would create the new buffer as the primary buffer only if there was no previously existing primary buffer; otherwise, the new buffer was just added as ``another'' buffer in the system. When you use OPTIONS RESULTS in the ARexx script so that the image processor knows it can return data to you, the number of the buffer created will be returned. This new command ensures that the newly created buffer will be the primary buffer, regardless of previously existing buffers in the system. ---------- newbuf (changed) ---------------- The ARexx newbuf command now returns the number of the buffer it creates if you use OPTIONS RESULTS in the ARexx script. ---------- fromdigiview (changed) ---------------------- The ARexx fromdigiview command now returns the number of the buffer it creates if you use OPTIONS RESULTS in the ARexx script. ---------- backuptoundo (new command) -------------------------- This command has specifically included to enhance the public interface capabilities. If you are writing an external process, and are operating upon the contents of the Primary buffer, using this command before you perform your process will copy the initial contents of the Primary buffer into the UnDo buffer, allowing the user to UnDo the changes caused by your process. ---------- coords [showattop] (new command) --------------------------------------- Here, is required, 0 means no, 1 means yes. ---------- grid (new command) ------------------------------------------------------- Here, is required and should be 1 for on, 0 for off. If is present, then the other four parameters must also be. and define the spacing of the grid. and define the offset from the top left edge of the image where the first vertice of the grid will occur. These last two parameters MUST be values less than the first two. ---------- autoactivate (new command) -------------------------- The autoactivate ARexx command has been added so that you can change the state of the image processor's automatic re-activation of it's main control panel when it completes all pending operations. Since there may be times when you have another process running, and don't want the image processor to reactivate it's window during that time, this command was added. Use it as autoactivate 0 to turn autoactivation off, and use it as autoactivate 1 to turn it back on again. If you are passing control to another program, make sure that autoactivate 0 is in the ARexx script before the other program is called; and when control is returned to the image processor, make sure that autoactivate 1 is in the script before you bring up the the image processor screens. Bringing the the image processor's display to the front with autoactivate off may seriously confuse the user. ---------- DISPLAYMODE (new command) ------------------------- DISPLAYMODE [quality] ------ for Image Professional DISPLAYMODE ----------------- for Imagemaster DISPLAYMODE ------------------ for Imagemaster F/c This command allows you to change the current display mode within the image processing software. It has no effect upon the image itself, nor upon output render results. In the following table, "Q" is used to specify the [quality] switch. for IP is 0 = luma 1 = avg 2 = reg Ord Dither 3 = HAM-E 24 bit (also depends on Q flag) 4 = HAM-E 18 bit (also depends on Q flag) 5 = EDD 256 colors 0 = non-lace 1 = lace display [quality] 0 = normal 1 = high quality (HQ) for IM is 0 = luma (in 16 shades) 1 = avg 2 = 16 color hi-res 3 = 32 color lo-res 4 = half-brite 5 = HAM (fast) 6 = HAM (quality) for IMFc is 0 = luma (256 shades) 1 = avg 2 = color (24 bit) (the second parameter is then ) 0 = low res 1 = med-res 2 = med-res 2 3 = hi-res ---------- render (changed) ---------------- The following replaces the description of the RENDER Arexx command on pages 177 and 178 of the manual. Summary of changes: - * 19 new render modes * No more size restrictions, except when rendering for DCTV (as required by the device). * Number of colors defaults to the maximum for that render mode. Detail ====== render [numcolors] --------------------------------------------------------------------- 0 = no, 1 = yes. Ignored for GIF and the non-viewable IFF renders. render image width. Only restricted to between 640 and 736 for DCTV. render image height. Only restricted when rendering for the DCTV to between 200 and 241 for non-lace and between 400 to 481 for lace. 1 = HAM-E mode, 18 bit 2 = HAM-E mode, 24 bit (extended color space dithering) 3 = Register mode for the HAM-E device, undithered 4 = Register mode for the HAM-E device, dithered (EDD) 5 = Register mode for the HAM-E device, Black and White average 6 = Register mode for the HAM-E device, Black and White luma 7 = 256 color GIF 8 = 16 shade Amiga hi-res - Black and White Average 9 = 16 shade Amiga hi-res - Black and White Luma 10 = 16 color Amiga hi-res - color 11 = 32 color Amiga lo-res 12 = 64 color Amiga half-brite 13 = Amiga HAM 14 = DCTV 3-bitplane (width must be 640 to 736, and height 200 to 241, or 400 to 482) 15 = DCTV 4-bitplane (width must be 640 to 736, and height 200 to 241, or 400 to 482) 16 = Amiga Hi-Res with 1 bitplane and 2 colors 17 = Amiga Hi-Res with 2 bitplanes and 4 colors or less 18 = Amiga Hi-Res with 3 bitplanes and 8 colors or less 19 = Amiga Lo-Res with 1 bitplane and 2 colors 20 = Amiga Lo-Res with 2 bitplanes and 4 colors or less 21 = Amiga Lo-Res with 3 bitplanes and 8 colors or less 22 = Amiga Hi-Res with 4 bitplanes and 16 colors or less 23 = Amiga IFF render (not displayed ) with 6-bitplanes and 64 colors 24 = Amiga IFF render (not displayed ) with 7-bitplanes and 128 colors 25 = Amiga IFF render (not displayed ) with 8-bitplanes and 256 colors If 0 the image colors will be chosen; if 1 then the currently loaded palette will be used. The image name used to save the rendered image to. The full name will be a combination of the render path that was set with the RENDERPATH command, this name, and the extension that was set with the RENDEREXT command. [numcolors] The number of colors used to render with. This defaults to the maximum number of colors possible for each render method. This only indicates the number of registers for Amiga HAM and HAM-E modes even though the actual number of displayable colors is much higher. (Ignored for DCTV renders.) ---------- Public Interface ================ Provided PI Modules ------------------- We have provided a number of PI modules with the image processor. These PI Modules provide: * JPEG load and save capability * PMBC load and save capability * RAW load and save (both color and B&W) * Direct insertion of an image to the FireCracker 24 Black Belt Systems has accomplished a number of ``firsts'' with these PI Modules; Our image processing software is the first commercial software on the Amiga to provide JPEG load and save capability, and the only software of any kind to provide PMBC save and load capability. ---------- Installing the PI Modules ------------------------- To install the provided modules, go into the directory on the release disk that is named the same as the PI module (JPEG, PMBC, RAW, etc) and read the file entitled ReadMe. This gives explicit directions on installation and use. Generally, a PI Module contains an ARexx script, and one (or more) CLI/shell commands. ---------- Image Locking ------------- This capability provides a safety net under all Public Interface Modules. What happens is that when an ARexx script LOCKs a buffer, it cannot be changed from inside the image processing software; this allows external processes to run long operations without the concern that user might quit the program and pull the rug out from under, so to speak. Image locking is done with the following commands: LOCKIMAGE UNLOCKIMAGE UNLOCKALL Note that the NEWBUF command now returns the buffer number if you set OPTIONS RESULTS before you call it. This conveniently provides the buffer number to lock without any further ARexx manipulation. ---------- Unlock Buffer (in Buffer Panel) ------------------------------- This is the "escape hatch" for the user if they believe that a buffer has been left locked by mistake. This should rarely, if ever, be used by the normal user. However, if you are developing PI Modules, it may come in very handy. Unlocking a locked buffer when it is still being accessed by an external process means that the image processor can delete the buffer, or even exit and delete everything - which means that the task that was writing into the buffer will now be writing in what the system thinks is free memory - very scary stuff. This button warns the user that unlocking isn't advised normally. ---------- Access to any buffer for PI Modules ----------------------------------- This is similar to what you can do with the JACKIN operation, but it is specific to a single buffer. The intent is to allow an ARexx script to create a new buffer which is NOT the primary buffer, and begin working on it without getting in the user's way; the user can continue to work normally, yet this other buffer is "happening"; for instance a ray tracer can render right into it while you do other things. Here are the relevant commands: UNPLUG plugpointer = PLUGIN which returns a pointer to a structure as follows: struct plugina { struct jackinbuff *buffer; unsigned char id[4]; / * 'P','L','U','G' * / }; ...where "buffer" points to: struct jackinbuff { unsigned char *red; unsigned char *green; unsigned char *blue; unsigned char *mask; unsigned short x; unsigned short y; }; The expected sequence of operations is to allocate a buffer, PLUGIN to it, LOCK it, do stuff to it, and finally UNLOCK it. Before you use a "plugina" structure, you should check the "id" array and make sure that the four characters P, L, U and G are in positions 0, 1, 2 and 3. If not, the structure isn't valid and your command should fail with a warning to the user. ---------- Structures ---------- If you are working with the Public Interface, you'll find these structures useful: /* * Structure that represents each buffer in IM */ struct rgbu { unsigned char *red; /* X by Y size array */ unsigned char *green; /* X by Y size array */ unsigned char *blue; /* X by Y size array */ unsigned char *mask; /* X by Y size array (?null?) */ unsigned short x; /* X size */ unsigned short y; /* Y size */ }; The rgbu structure represents the data built for you about each of the buffers (Primary, Secondary, Brush, Blend, Undo). In the case of the UnDo buffer, the mask pointer will always be NULL. The red, green and blue pointers point to a linear array of unsigned bytes where 0 is fully dark, and 255 is fully bright for that color. The mask pointer, if present, points to an array of unsigned bytes that will contain non-zero values where the image exists, and zero where it does not. If you write image data in regions of the red, green and/or blue buffers that is masked (mask is zero), the user will never see it. The memory is there and you may write in it if you feel you have a good reason (temporary storage?). The x and y values represent the x and y dimensions of the buffer. Buffer data is arranged X first, then Y. If an image is 320 by 200, the first pixel of the first line is at offset 0 in the buffer; the second pixel in the third line is at offset 961. You can locate pixel data using the following formula, where ``x'' is the width, Y is the current Y position and ``X'' is the current X position: p = (Y * x) + X This should be all the information you need to utilize the data in the rgbu structure. /* * Represents the main info struct in IM */ struct jacker { struct rgbu *pr; /* Primary Buffer */ struct rgbu *se; /* Secondary Buffer */ struct rgbu *un; /* UnDo Buffer */ struct rgbu *bl; /* Blend Buffer */ struct rgbu *br; /* Brush Buffer */ unsigned char *msk; /* User Mask (Primary-size) */ char jack[4]; /* verify: chars J,A,C,K */ struct Screen *showscr; /* screen of gadget panel */ unsigned char pname[4]; /* image processor name: 'IP'00 'IM'00 or 'IMFC' */ long ver; /* version of the program */ }; The jacker structure contains only two types of data. First, there is a group of pointers to the various rgbu structures that represent the state of those buffers within the system. If one of these pointers is NULL, then that buffer does not currently exist. Next, there is a pointer to a mask. This mask is always the same size as the Primary buffer; it will only exist if there is a Primary buffer; and as a result, you can get the X:Y size of the mask by examining the X:Y sizes specified in the rgbu structure for the Primary buffer. ---------- PI Module Code Examples ----------------------- The following code fragment assumes the use of the above structures. It is the beginning of a CLI command which accepts the pointer passed in from the ARexx script fragment shown, and then checks for reasonable values in the structures. There is an additional item in the jacker structure which is a short character array that is loaded with the four ASCII characters J, A, C and K. This is not documented in the manual, but it is there in all cases and you should ALWAYS check for it before assuming that everything is ok to proceed. You should always do this, or it's equivalent, when beginning a process operation upon the primary buffer: void main(argc,argv) int argc; char *argv[]; { int tot,i; struct jacker *j; unsigned short dx,dy,x,y; if ((argc != 2) || (strcmp(argv[1],"?")==0)) { printf("%d arguments...\n",argc-1); printf("Requires one argument:\n\n"); printf("'JACKIN' hex pointer\n\n"); exit(1); } sscanf(argv[1],"%x",(int *)&j); /* *jackin */ if (j->pr == 0) { printf("No Primary Buffer!\n"); exit(2); } if ((j->pr->x == 0) || (j->pr->y == 0)) /* bad */ { exit(3); } if (j->jack[0] != 'J') exit (4); /* check sanity */ if (j->jack[1] != 'A') exit (5); if (j->jack[2] != 'C') exit (6); if (j->jack[3] != 'K') exit (7); /* * We got here, so there IS a primary * buffer. We can now proceed... */ The previous example used a value passed by the following ARexx code fragment: address 'IM_Port'; /* talk to the image processor */ options results; /* allow replies */ 'jackin'; /* get pointer to structs */ jackadr = result; /* copy return value */ options; /* disallow replies */ 'wbtofront'; /* bring WorkBench up */ address command 'c:ccpr '||jackadr; /* send... */ This ARexx fragment, or something extremely similar to it, is what you use to send the Public Interface pointer to your custom process, image loader, or image render program. Note that in combination with the other ARexx commands for panels, file requesters, area control specifiers and so on you can create a great deal of the required logic for your tool(s) using nothing more than the ARexx interface. There is a complete example of a "process" type of PI Module on the release disks, with SAS C source code, ARexx, and linkable object modules which provide progress bar indication and control panel based message services.