ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / graphics / widget5_1 / !Widget5 / !Help < prev next >

Wrap

Text File | 1995-11-08 | 33KB | 829 lines

Instructions for !Widget5 by Andrew Sellors ***************************************************************************** * NOTE: * * !Widget5 is FreeWare. * * This means that you may freely copy and distribute it, provided that it * * is complete with all original files, and that you do not sell it. * * PD libraries may charge a nominal fee for the cost of duplication, * * postage etc. * * In no circumstances shall the author be liable for any damage, loss of * * profits, time or data or any indirect or consequential loss rising out of * * the use of this software or inability to use this software. * ***************************************************************************** Contents: ~~~~~~~~~ About Widget 5 Compatibility Operation Managing Filters Filter File Format Drawing Masks Configuration Window Security Setting the 3D bit Credits The Future Contacting the author ******************************************************************************** About Widget 5: ~~~~~~~~~~~~~~~ * Widget 5 is a 256 grey level image processing package for square pixel Sprites. * Widget 5 will work with any size of image, memory permitting. * Widget 5 loads any file as a 256 grey level image, disregarding any palette. (Useful for owners of the Brainsoft video digitizer) * Images are stored in 12 separate "Image Banks" in memory. * Widget 5 can be run in any screen mode, but those which have 256 grey levels in the palette will result in the best images. * Widget 5 will store the images in a dynamic area when used with RISC OS 3.5+ * Widget 5 can load and saved squashed sprite files to reduce disc usage. * Widget 5 supports the following image manipulation functions: * Add two images * Average two images * Mix two images * Convolve an image to another using a NxM matrix (N,M in the range 1-9) * Focal Analysis with the following localised processes on a 3x3, 5x5, 7x7 or 9x9 patch: * Mean greylevel * Median * Maximum * Minimum * Changing image greylevels by: * Drawing the mapping function using the mouse * Applying a threshold value * Applying a gamma correction value * Applying histogram equalization * Applying S.L.C.E. (Saturating Linear Contrast Enhancement) * Scaling an image by resampling using bi-linear interpolation * False colouring selected greylevel ranges and calculating the percentage of each range. * Levels slice by false colouring equally spaced sections of the total grey level range to a defined number of sections and calculating the percentages of pixels contained in each of the ranges. * Widget 5 allows an irregularly shaped area mask to be defined to allow localised processing. * Area masks can be loaded and saved as text files of point coordinates. * Widget 5 allows the image to be zoomed using the usual magnifier window * Widget 5 can draw the following graphs from an image: * Greylevel histogram * Cumulative histogram * Individual bar heights can be inspected on the graphs. * Graph data can be saved as a CSV file to allow importation into another package for analysis. * Widget 5 allows Convolution Filters to be loaded and saved. * Widget 5 uses the 3D bit in CMOS RAM to select 2D or 3D windows _and_ iconsprites on startup. (See the "Setting the 3D bit" section if you don't like 2D windows) ******************************************************************************** Compatibility: ~~~~~~~~~~~~~~ This program is for RISC OS 3.10 or later. It has been tested on both RISC OS 3.10 and RISC OS 3.50. ******************************************************************************** Operation: ~~~~~~~~~~ NOTE: Clicking on an action icon with Adjust performs the action but leaves the window open If a window contains icons where text can be entered in then pressing the RETURN key when in the last icon has the affect of selecting the default action button (the one with the yellow border if 3D windows are used). About Image Banks ================= When held in memory, an image is assigned an Image Bank number so that it can be referenced to for subsequent operations. This is shown on the title of the image window and also on the menu displayed when the menu button on the mouse is pressed over an image. Operations chosen from the menu on the image window always use that Image Bank for the source image. When an image window is closed, the image is discarded from memory and the Image Bank becomes free. Starting up =========== The !Widget5 application starts up when you double-click on its filer icon. Creating a blank image ====================== Clicking on the icon bar icon displays the create image window. The size of the image can be changed by typing or using the arrow icons. The radio icons determine which image bank the image is created in. Used image banks icons are greyed out. Loading a file ============== When a sprite file is dragged to the icon it is loaded into memory and the place image window is displayed. This allows the image to be placed into one of the Image Banks. Unavailable banks are greyed out, if they are all greyed out then free one of the banks by closing the window, but remember to save the image first if you want to keep it! More that one image can be loaded without being placed in a bank, and an image can be loaded (but not placed) when all the image banks are used. Loading squashed sprites ======================== Squashed sprite files can also be loaded into Widget 5 in the same way as normal sprite files. These are the same as the files saved by the !Squash application that comes with the machine and save disc space by storing the data in a compressed form. Only Squashed sprite files can be loaded, an attempt to load a file which does not contain a squashed sprite will return an error message. Image menu ========== Pressing the menu button over one of the Image Banks displays the menu for that bank. The Image Bank number is repeated on the menu title. The "Info" subwindow shows the size and memory usage of the Image Bank, total number of used greylevels in the image and the overall greylevel range. The "Save" submenu allows the image to be saved as a 256 grey level sprite. The name of the sprite in the file it set to the same as the filename (up to a maximum of 12 characters). Selecting the "Save squashed" option will result in the sprite being saved as a squashed sprite and so saving disc space. The "Process" submenu allows one of the image processing operations to be selected. These operation will use the Image Bank as source that the menu was open over. The "Graph" submenu allows graphs to be generated for that particular image. The "Zoom" subwindow allows the size of the image to be changed on screen. Clicking on the "Zoom" entry itself displays the zoom window statically. The image that the zoom window refers to is displayed in its title and the zoom window is always kept above that image window. The "Add mask" option adds a mask to that image bank and displays the mask tools window. If the image bank already has a mask then the option is greyed out. Using Masks =========== Many process windows have "Use Source Mask" and "Copy Outside" options. These options control how the mask defined on the source image is used by the process. If the source image does not have a mask defined then these options are greyed out. The "Use Source Mask" option when selected makes the process only apply to pixels within the mask area on the source image rather than on the whole image. The "Copy Outside" option, when used in conjunction with the "Use Source Mask" option results in the pixels around the masked area to be copied unchanged from the source image. With this option off, the pixels around the mask area in the destination image are left unchanged. Pixel Display ============= Clicking with the Adjust (right hand) mouse button over the image window displays the pixel display window which shows the X and Y coordinate of the pixel under the pointer and also the greylevel and a display of the intensity. The window remains whilst the button is held down and is updated as the mouse is moved around the image. Processes ========= Copy: ----- This copies the image to another bank. Add: ---- This adds the grey levels in the source bank to those in the destination bank. Average: -------- This adds the grey levels in the source bank to those in the destination bank and then divides by 2. Mix: ---- This mixed the image in the source bank with another to produce a third which can be placed in the same bank as the second source image. Clicking on "Start" on the source and destination selection window replaces it with a second window containing a horizontal slider. This slider allows the proportions of each image (shown below each end of the slider) to be changed by dragging the sliderbar. Normally the resulting image is only created when the "Mix" icon is clicked on , but if the destination Image Bank is different from both the source Image Banks then the "Real-time" option can be selected. This updates the resulting image when the mouse is released from the slider allowing different values to be tried out easily. Convolution: ------------ This performs a NxM convolution, where N and M can be any value between 1 and 9, using the matrix and anchor point selected. The values of the matrix and anchor point can be entered by typing numbers into the icons or selecting pre-defined filters from the pop-up menu. The matrix size can be selected by clicking on the up and down arrows by the numbers indicating the current size or by clicking on one of the size buttons, eg. "3x3". The menu of pre-defined filters only shows the filters for the selected matrix size. The matrix size and anchor point values are shown as "ROWS X COLUMNS". For the anchor point, 0,0 is the centre of the matrix with positive coordinates in the right hand and upward direction. When changing the size of the matrix, if the caret is in the matrix it is always returned to the centre (0,0) of the matrix. The matrix is overlayed on the source pixel (positioned under the anchor point) and the overlapping values multiplied and summed together. As the resultant value for each pixel after the convolution is normally scaled in some way, the "Scale" value is provided to scale the value back to the 0 to 255 range of greylevels. This value is used to divide the result before it is written into the destination image. Clicking on the "Auto" button calculates the gain of the matrix and places it in the scale value. This value will on average return the result back into the desired range. The "Offset" value is provided to shift the grey levels up or down before they are written. If the gain of the matrix is zero then it removes the D.C. component resulting in negative as well as positive results. A positive offset of 128 for example will ensure that the negative results are shifted up and not lost. Clicking on the "Clear" button sets all the values in the matrix and anchor point icons to zero. Clicking on the "Save" button displays the "Save Convolution Filter As" dialogue. This allows the values of the filter matrix and anchor point to be saved to a file for later use or added to the list of filters in memory. See the section titled "Managing Filters" further on in this manual for more details. Focal Analysis: --------------- This performs various localised processes on the image. The size of the patch of the image around each source pixel taken for the process is selected in a similar way to the convolution matrix size with the row of size buttons. An anchor point, also like in the convolution process, is provided to offset the patch from the destination pixel position when it is placed over the source image. These processes take the pixels contained by the patch in the source image and process them to produce the value that is placed in the destination image. Mean: ===== The mean (average) value of the set of source pixels in the patch is calculated and if the difference between that and the original source pixel is less than the threshold set in the submenu then this value is written to the destination image. If the difference is greater than the threshold then the original greylevel from the source pixel is used for the destination. The threshold is provided to lessen the blurring on edges where a large transition between grey level values occurs. L.A.C.E.: ========= Not implemented yet :-( Median: ======= The set of source pixels in the patch are sorted into numerical order and the median (middle) value is selected for the destination pixel. This is a smoothing process which is particularly suited to removing scratches from images. Maximum: ======== The maximum greylevel in the source patch is selected and used for the destination pixel value. Minimum: ======== The minimum greylevel in the source patch is selected and used for the destination pixel value. Percentage Cover: ----------------- This allows ranges of greylevels to be selected and false coloured in the image. Beside the image window is displayed another window showing the colours and greylevel ranges selected as well as the percentage of the whole image containing pixels in each of the ranges. Colours are selected by turning on the option button beside the relevant colour box. This ungreys out the two writable icons into which the range of greylevels for that colour is typed. Clicking on "Colour" false colours the current image with the parameters selected. If "Copy to new image" is selected then the current image is copied to the "New Image" image bank before being false coloured. Closing the window attached to the image bank window that shows the percentages causes the image colours to revert back to the normal greyscale. The colours are preserved in the file when the false coloured image is saved as a Sprite. As Widget 5 ignores any palette when loading an image, reloading this image will result in the colours changing back to the original greyscale but if the image is loaded into !Paint for example then the colours can be seen. Levels Slice: ------------- This splits the full range of used greylevels into a selected number of equally spaced sections. These ranges of greylevels are false coloured and have their percentages of pixels in each of the ranges calculated like the percentage cover process. Clicking on "Colour" false colours the current image using the number of levels selected. If "Copy to new image" is selected then the current image is copied to the "New Image" image bank before being false coloured. Closing the window attached to the image bank window that shows the percentages causes the image colours to revert back to the normal greyscale. Greylevel Edit: --------------- This allows the greylevels in the source bank to be mapped to different ones and the resulting image placed in another bank. Clicking on "Start" on the source and destination selection window replaces it with a second window that performs the actual functions. The large box shows the mapping function that maps the greylevels in the source image (along the bottom of the box) to the resulting image (up the side of the box). "0" is completely black and "255" is completely white. The mapping function can be changed by clicking in the box and drawing the line for the new mapping function. When you hold the button down, the greylevels in the source and destination images for the current point in the box are displayed. Levels of smoothing can be applied when drawing the mapping function. If "Normal Draw" is selected, then only the point in the line where the mouse pointer is positioned is affected. If either "Smooth Draw" or "V. Smooth Draw" is selected then the points near the mouse pointer are also affected, the latter of which producing a greater affect. This allows less jagged lines to be drawn. Various mapping functions can also be selected from the "Processes" menu displayed by pressing the "Menu" mouse button when over the window. "Linear" produces a resulting image identical to the source. "Invert" produces a negative of the source image. "Threshold" makes all the levels below the value black and above white. "Gamma" applies gamma correction using the value entered in the submenu. "Histogram" applies histogram equalization on the source to give the maximum possible contrast. "S.L.C.E." applies Saturating Linear Contrast Enhancement on the source to enhance the contrast in the image. This looks much better than histogram equalization as the resulting image is less harsh. Selecting "Real-time" results in the destination image being updated after every operation instead of just when "Map" is selected. The image is updated when the mouse button is released after drawing on the mapping function and when any of the processes have been selected. The arrow buttons on the submenus for the Threshold and Gamma processes can be used to adjust the values. If the SHIFT key is pressed when the arrows are clicked upon makes the values change faster. If the "Real Time" option is selected then the image is updated as the values change. Scale: ------ This allows the source image to be scaled by resampling using bi-linear interpolation. When an image is enlarged using this process the "blockiness" , caused by the pixels being enlarged, is reduced. The new size can be selected from either a percentage of the original size, "To Fit" a resolution which can be typed in the two icons or to "Custom" x and y scaling ratios. Graphs ====== The "Greylevel Histogram" graph shows the number of pixels using each greylevel in the source image. The "Cumulative Histogram" graph shows the total population of pixels in the source image at and below the grey level shown on the x axis. Thus if the greylevels are linearly allocated (ie. there is an equal number of pixels having each greylevel) then the graph is a straight line between the bottom left and top right. The greylevel and height of the currently selected bar is shown on the bottom of the graph. The selected bar is shown in blue instead of the normal red. Clicking on a part of the graph updates the greylevel and bar height display to the bar under the pointer. The up and down arrows can be used to move the currently selected bar and pressing the SHIFT key when clicking on the up or down arrow makes the greylevel move faster. Pressing the menu mouse button over the graph displays a menu that allows the graph data to be saved as a CSV (Comma Separated Variables) file and the size of the graph to be changed. ******************************************************************************** Managing Filters: ~~~~~~~~~~~~~~~~~ Widget 5 holds a set of convolution filters in memory that can be accessed by the pre-defined filter menu in the Convolution Process window. The filters are referenced by size (ie. the number of rows and columns in the matrix) and filter name. The filter menu only shows the filters for the selected matrix size, or "None Found" if none are defined for that particular size. When Widget 5 starts up it scans all the files in the default filters directory and loads up the filters that are present in the files to be shown in the menu. The location of this directory, which is by default, !Widget5.Filters, is setup with the system variable "<Widget5Filters$Dir>" in !Widget5.!Run. To add filters so that they are loaded on startup, simply place the files in the Filters directory (the !Widget5 application directory can be opened by double clicking on the filter icon with the SHIFT key pressed). If you want to place the directory somewhere else then just edit the !Widget5.!Run file with a text editor such as !Edit. By dragging a filter file to the Convolution Process window the first filter in the file is used to set the values of the matrix and anchor point. This allows a library of filters to be built up and selected easily. By dragging a filter file to the Widget 5 iconbar icon, all the filters in the file are loaded up into memory to appear on the filter menu. When the "Save" button in the Convolution Process window is clicked on, a copy of the filter matrix and anchor point coordinate is taken and the "Save Convolution Filter As" dialogue is displayed. The name with which the filter appears in the menu and is reference by must be entered in the "Filter Name" icon. This window allows the convolution filter to be saved to a filter file by either dragging the filter file icon to a filter window or by typing in the full pathname for the file and clicking on "Save". As this overwrites a file if it is already present, Widget 5 prompts for conformation if a file will be overwritten. If "Add To Current" is selected then the filter is added to the end of a filter file already on disc rather than replacing it. This way, more than one filter can be added to a particular file. If "Add To Memory" is clicked on then the filter is added to the list of filters stored in memory and so will appear in the filter menu. This does not mean, however, that the filter will be present the next time Widget 5 is loaded. If "Save To Default" is clicked on then the filter is added to the default filter file. This is a file in the default filters directory that holds the default filters. Thus by clicking on this button, the filter will be loaded next time Widget 5 starts. The filename of this file is also setup in the !Widget5.!Run file with the system variable "<Widget5$FilterDefault>". The default is !Widget5.Filter.Default. As the filters are referenced by size and name, two filters with the same matrix size and name cannot be present in memory at the same time. For this reason, an attempt to do this by either loading a filter file or adding a filter to memory using the "Save Convolution Filter As" window will result in an error message being displayed showing the name and size (and the filename of the file holding the file where applicable) of the duplicate. For this reason an error is also displayed if an attempt is made to add a duplicate filter to a filter file. ******************************************************************************** Filter File Format: ~~~~~~~~~~~~~~~~~~~ Convolution filters are stored in text files so that they can be easily edited and created manually. A filter definition in the file consists of a block of lines without any blank lines between the lines for a particular filter. Blank lines are allowed between different filters. Numbers in a line are separated by commas (,). Leading spaces, and spaces between the numbers and the separating commas are ignored. The first line of the block contains the name of the filter. The second line contains the size of the filter as "rows,columns". The third line contains the anchor point coordinates in the form "row,column". The subsequent lines contain the matrix values, one line for each row in the matrix. eg. Smooth 0,0 3,3 0,1,0 1,1,1 0,1,0 Defines a 3x3 matrix called "Smooth" with an anchor point of 0,0 and a matrix, [ 0 1 0 ] [ 1 1 1 ] [ 0 1 0 ] ******************************************************************************** Drawing Masks: ~~~~~~~~~~~~~~ When a mask has been added to an image bank, the mask tools window is displayed, giving access to tools that allow the shape and position of the mask to be defined and the points saved as a text file for later use. Dragging a text file containing a list of points to the mask tools window, loads the points in as a new mask shape. The mask outline is shown as a red line over the image. The points on this shape are marked by either green squares or yellow triangles to indicate selected points. Add Point tool The first tool button on the left allows points to be added to the mask shape by clicking on the image with Select at the required position and is added on the shape between the two selected points. The currently selected points can be changed by clicking on the green squares. Move Point tool The next button allows points to be moved. This can be done by either dragging a point with the mouse to the required position or by using the arrow buttons on the tool window to move the selected point one pixel at a time. The coordinates of the selected point are shown in the tool bar together with the greylevel of the pixel under the point. These values are updated as the point is dragged or moved using the arrows. If the SHIFT key is pressed at the same time as the arrow icons then the point moves faster. Delete Point tool The next button allows points to be deleted from the mask shape by clicking on the relevant green squares to remove that point. Points can no be deleted when only two are left otherwise there is no shape! Filled Shape tool The next button causes the area inside the mask shape to be filled in yellow. This allows the shape of the masked area to be seen clearly. Memory Display Next along the line at the bottom is the amount of memory that the mask uses. This memory is freed when the mask is discarded. Copy Mask To the right of the memory display is a pop-up menu button that allows the shapes of masks present on other image banks to be copied over. If no other images have masks then the menu says "No masks". Save Mask The next button displays a save box allowing the mask points to be saved as a text file. This allows masks to be stored and used later by dragging them from the Filer window to the mask tools window. Discard Mask The last button removes the mask from the image bank and frees the memory that it takes. Don't use this if you still want to use the shape as once it is gone, it cannot be retrieved unless it was saved as a text file. ******************************************************************************** Toolbar: ~~~~~~~~ Most of these icons are self explanatory (or at least I hope so :-) A point worth noting, however is that the histogram button performs two actions, the a Select mouse click displays the Greylevel Histogram and an Adjust click the Cumulative Histogram. ******************************************************************************** Configuration Window: ~~~~~~~~~~~~~~~~~~~~~~ The configuration window can be opened by selecting the "Configure..." entry from the iconbar menu. The window allows program-wide options to be setup and the configuration saved so that it is used when the program is next loaded. "Process Destination" ===================== This affect the way the destination banks are picked for the processes. "Only use free banks" only allows you to pick banks that are unused for the destination image. "Use free or same size banks" allows you to pick banks that are either free or contain an image that is the same size as the source. "Graph Size" ============ This determines the size of the graphs that are drawn. The large size is ideal for 17" monitors. "Draw action" ============= These determine the default selection of the draw action options in the greylevel edit process window when it is displayed. "Update" ======== This determines the default selection of the "Real-time" option when the process windows that use it are displayed. "Image Memory" ============== This determines whether the images will be stored in a dynamic area or in the application's normal wimpslot. The location can only be changed when no images are present in memory and dynamic areas can only be selected on machines that support it. "Image Titles" ============== Turning "Show process name" on will place the name of the process and source image bank(s) onto the title of an image window created by a process. "Squash Sprites" ================ Turning "Save squashed" on selects the option of saving the sprite files as squashed files by default when the save dialogue is displayed. "IO buffer size" is the amount of memory claimed when loading or saving a squashed file to be used to buffer the reads and writes to and from the disc. A value of 0 is not allowed in this field. A small value slows down compression/decompression. "Double Click Loads" ==================== These options select which files Widget 5 will load when their icon is double clicked upon in the filer window. When selected that particular file will be loaded on double click unless another program that loads it has been loaded previous to Widget 5 (like !Paint for sprites) and is shown to the right of Widget 5's icon on the icon bar. Clicking on "Change" applies the changes made and closes the window. Clicking on "Cancel" forgets the changes made and closes the window. Clicking on "Save" applies the changes made and saves the new configuration so that it is used the next time the program is loaded. "Toolbar" ========= The "Show" options selects whether the toolbar is present on the side of the image bank windows. If you don't like toolbars then you can turn it off. ******************************************************************************** Security: ~~~~~~~~~ If anything should go wrong with Widget5 and the program has to exit due to an unrecoverable internal error, the option is provided of saving any loaded images before the program quits. Clicking on 'OK' when the error message is displayed saves the images by the image bank number in a directory 'Widget5' in the Scrap Directory (in the !Scrap application). ******************************************************************************** Setting the 3D bit: ~~~~~~~~~~~~~~~~~~~ If you want to use the 3D windows in this program (and the handful of others that support it) then you need to set the 3D bit in the CMOS RAM. !Configure in RISC OS 3.5 allows you to change this, it is the called "2D window tools" in the "Window manager" window and should be off to have 3D windows (which is where it normally is). In RISC OS 3.1 the only way to do this is to: Cut out the following BASIC program and run it. Note: this program toggles the bit, so if its off and you run it twice then it is still off! 10REM Toggle state of '3D look' bit in CMOS 20REM Read byte 30SYS "OS_Byte",161,140 TO ,,byte% 40REM EOR byte with mask for bit 0 50byte% = byte% EOR 1 60REM Write byte back again 70SYS "OS_Byte",162,140,byte% 80END ******************************************************************************** Credits: ~~~~~~~~ Many thanks must go to Jeremy Cook whose suggestions, encouragement and toolbar sprites have made Widget 5 what it is today. ******************************************************************************** The Future: ~~~~~~~~~~~ Widget 5 is not finished! Many improvements are planned although they won't be implemented for a while which is why this release has been made. To wet your appetites, here is a selection from my "To Do" list: Configurable toolbar. Proper Dynamic Area memory management. Better mask control. (process inside or outside mask shape) L.A.C.E. on Focal Analysis process. Algebra process with +-/etc. Transformation process with rotation, mirroring, transformation etc. Statistics info window with s.d, mean, mode, etc. Optimised ARM coded processing routines (at the moment they are just ordinary C) Any suggestions will be gladly accepted, as without suggestions it cannot get better. ******************************************************************************** Contacting the author: ~~~~~~~~~~~~~~~~~~~~~~ I, Andrew Sellors, can be contacted either at 57 Boundaries Road Feltham Middlesex TW13 5DR England Or via Internet email at asellors@orac2.demon.co.uk Any feedback from users (bugs reports, requests for new features, praise, money etc.) is gladly received.