Batch2Fit.ifx Documentation ============================= v1.01 By Ross Fenmore © 1996 Light Source Video & Graphics This documentation is presented in the form of questions and answers. Content is as follows: ============================================== What is Batch2Fit.ifx (B2F)? What does B2F do? What are the basic features of the program? How do I use B2F? How do I stop B2F if something goes wrong? Is there a way to speed up B2F processing? How do I use AmigaDOS wildcard patterns? What are some of the program's limitations? Where do I reach the author? ============================================== What is Batch2Fit.ifx (B2F)? ---------------------------- B2F is an ARexx script written for ImageFX 2.1 (tested on 2.1.2027). It is accessed by clicking on the [Arexx] button on the ImageFX ToolBox Panel and choosing the script by name from the file requester presented. What does B2F do? ----------------- B2F is a batch processor designed for a fairly specific application: Scale a number of images of varying sizes to a user specified page size while maintaining the original image aspect ratio. Center the result on a black background with a user specified screen size. Save the resulting images in the format of choice and with a user specified naming convention that maintains at least part of the original filename. This script was inspired by an article in the February 1996 issue of Video Toaster User Magazine by Michael McBride that described a rather involved method for converting images designed for print in a DTP program to images that could be displayed by the NewTek Video Toaster. Refer to that article for a detailed explanation of what B2F was designed to do. The entire process is automated using B2F. What are the basic features of the program? ------------------------------------------- /* Composite a directory of images over a black backdrop */ (No backdrop image required) /* A filename pattern can be entered for inclusion/exclusion of files */ /* Selectable output file format, directory, and filename extensions */ /* Automatic Framestore filename building with sequential FS numbers */ (Original filenames preserved) /* Optional stripping of source filename ".xxx" (dot extension) */ /* Choose a screen size and margins to constrain images to page size */ (Keep important information out of overscan area) /* Images are scaled to page size and centered on screen size */ /* Aspect ratio of original image is maintained */ /* Pixel aspect ratio adjustment for NTSC conversion is optional */ (Print 1:1 to Framestore 11:13) /* Gamma/Dynamic range filtering for NTSC is optional */ /* Scaling smaller images up to page size is optional */ /* A report is generated providing information on all processing */ How do I use B2F? ----------------- First, you need a directory of images to process. The images can be in any format recognized by ImageFX 2.1. Make sure the applicable Loader is located in the 'ImageFX:Modules/Loaders' directory. In ImageFX, launch the Batch2Fit.ifx macro as described above. You will be presented with a requester for entering all the necessary information required by B2F. All information will be remembered for subsequent invocations of B2F until a system reboot. Here is a gadget-by-gadget description of each requester item. Source Directory Path: ---------------------- The full path directory specification for your source images is displayed here. Initially, B2F uses the DEFAULT LOAD PATH you've specified in ImageFX Prefs. *** Enter your source path by using the file requester *** *** button to the right of the source path text. *** *** This is not a text entry gadget! It is for display *** *** purposes only. All entries here are ignored! *** Use the FILE REQUESTER BUTTON to select the directory where your images are located. If you want to enter an AmigaDOS wildcard PATTERN to include or exclude files, then enter it in the requester. The default is that all files in the selected directory (excluding '.info' files) will be processed. If you do not have facility with the use of wildcard patterns, then it is probably safest to make sure your source directory contains only the files you wish to process, and then just accept the default PATTERN. Because no synchronization between requester fields is provided by ImageFX's ARexx implementation, the text gadget to the left of the file requester button will NOT be updated after you select a source directory. After you enter all information in the B2F requester and select 'Okay', another requester will be presented where you can confirm your choices and cancel if necessary. Destination Directory: ---------------------- This is the full path directory specification where the processed files will be saved. Initially, B2F uses the DEFAULT SAVE PATH you've specified in ImageFX Prefs. *** Enter your destination path by using the requester *** *** button to the right of the directory path text. *** *** This is not a text entry gadget! It is for display *** *** purposes only. All entries here are ignored! *** Use the FILE REQUESTER BUTTON to select the directory where you want the scaled images to be saved. Because no synchronization between requester fields is provided by ImageFX's ARexx implementation, the text gadget to the left of the file requester button will not be updated after you select a destination directory. After you enter all information in the B2F requester and select 'Okay', another requester will be presented where you can confirm your choices and cancel if necessary. Output Format: -------------- B2F needs to know what graphic file format to use when saving your images. You select the format you want with the Output Format cycle gadget. Included formats are: ILBM Normal Amiga 24-bit RGB images FS Toaster Framestores JPEG JPEG compressed files OTHER Format specified in text gadget If you choose 'OTHER': Enter the name of the ImageFX saver you want to use in the text gadget to the left of the cycle gadget. Make sure the spelling is identical to the file listed in the 'ImageFX:Modules/Savers' directory. If you choose ILBM, FS, or JPEG, you do NOT need to enter a format in the text gadget. In these cases, the text gadget will be ignored. If you choose JPEG saving, a requester will appear once and will allow you to choose a 'QUALITY' setting with a slider bar. Because no synchronization between requester fields is provided by ImageFX's ARexx implementation, the text gadget to the left of the Output Format cycle gadget will not be updated after you select a format with the cycle gadget. The text field might not agree with the cycle gadget, so keep in mind, it is the cycle gadget that displays the selected format. After you enter all information in the B2F requester and select 'Okay', another requester will be presented where you can confirm your choices and cancel if necessary. Filename extension: ------------------- Enter the extension that you want B2F to add as a suffix to all image filenames saved. The characters that you type here will be appended to the existing filename of the source image that is being processed. Leave the text field blank if you don't want a filename extension added. A dot (.) is not added automatically, so specify one if you want one. The Filename extension field has a hidden capability. If you enter a number here, and the output format you've chosen is the Framestore format, then the number will be used as the first in a sequence of numbers used to build valid Framestore filenames. Example: Entering '450' (no quotes) would produce filenames of '450.FS.xxxxx', '451.FS.xxxxx', etc. where 'xxxxx' is the original filename truncated to 12 characters as required. If you want to save Framestores with regular filenames (you have a Flyer or Toaster 4.0), then don't enter a number for the file extension. Strip Source Extension? ----------------------- Activating this check box causes existing dot (.) extensions to be stripped from your source filenames before they are renamed for saving. This occurs before a selected filename extension is added as chosen above. By default, this box is checked. Screen width and Screen Height ------------------------------ Enter numbers in these boxes for the screen size you would like the scaled images to be centered on. The default size is 752 by 480 (size of Toaster Framestores). X Margins and Y Margins ----------------------- Enter numbers in these boxes for left/right and top/bottom margins that will be subtracted from the chosen screen width and height. An X margin of 20 and a Y margin of 15 would result in a page size of 712 by 450 for Toaster Framestores. (The screen size remains 752 by 480) If there's information at the edges of your images, then choosing appropriately sized margins will keep it out of the overscan area of the video screen. The default margin sizes are zero. NTSC Filter? ------------ This is an option for optimizing images for NTSC video display. Whether this will improve your particular images is somewhat of a subjective decision and one that requires some knowledgable evaluation. This filter will boost the gamma and then reduce the dynamic range of the image so that it is closer to within NTSC standards. If the source images were the result of underexposed photographs, this process will improve them greatly. Dark areas will show more detail. Also, saturated colors will bleed and smear less. On the other hand, if you don't want your pure whites and yellows to be dulled a little, leave this option off. Gamma is boosted by +50, Dynamic Range is adjusted to 0-220. These values work fairly well, however, if you find this option useful, but need more control over the values, email me and I'll program in some more requesters. Scale up? --------- This checkbox will indicate whether source images that are already smaller than the calculated page size are to be scaled up to maximize their size on screen. Obviously, image quality can be sacrificed if the scaling percentage is great. The default choice is not to scale up. Adjust NTSC Pixel Aspect? ------------------------- This checkbox will indicate whether source images are scaled so as to compensate for the difference in the 1:1 pixel aspect of print/scanned images, or images from other platforms, and the 22:26 pixel aspect of NTSC video. If your images look too tall and thin when viewed as Framestores, then activate this option. When you've entered all the required information in the B2F requester, click 'Okay' and you will be presented with a second similar requester showing you all the settings you've chosen. Although it may appear as if you can correct any mistakes, NO NEW ENTRIES WILL BE ACCEPTED, so CANCEL and start over if any selection is incorrect. Otherwise, click 'Okay' again and let B2F do its thing. As images are being processed, B2F writes a report about what it is doing. When processing is completed (or aborted) you will find a file in RAM: called 'BatchReport'. It is a plain text file. BatchReport includes the following: Date and Time Number of images to process Screen and page size Whether NTSC filtering is being performed For each image processed: Original size Pixel Aspect adjustment (if scaled) Scale factor and new image size (if scaled) Output filename You may want to copy RAM:BatchReport over to your hard disk after processing files for future reference. Also, if RAM:BatchReport already exists because you've run the script more than once since rebooting, the program will ask you if you want to replace (overwrite) or append to the BatchReport file. How do I stop B2F if something goes wrong? ------------------------------------------ Unfortunately, it may not be as simple as you'd like. I've included a SIGNAL ON BREAK_C in the script, however I've never been able to get it to work on my system. (Try pressing the Ctrl+C key combination and if it works, disregard the steps described below.) Instead, I've had to implement the 'abort process' differently. To abort B2F: 1. Press Left_Amiga-n to go to the Workbench. (Make sure WB isn't closed in IFX Prefs before you start the script.) 2. Activate the WB by clicking anywhere in its window. 3. Choose from the 'Workbench' menu 'Execute Command...'. 4. In the 'Command' text box, enter 'hi'. (2 letters, no quotes) 5. Hit [RETURN] on the keyboard or select OK. 6. Wait. As soon as IFX finishes loading or saving the current image, the IFX screen will come to the front and you can acknowledge the 'abort'. This may take a few moments. The BatchReport in RAM: will still have info on everything that was processed before you aborted. Is there a way to speed up B2F processing? ------------------------------------------ I like to see that the script is working, so I have the screen redrawn for each completed file (image). You can speed the redraw up if you set your Preview screen up with a limited number of colors and even a lower resolution. That way you can still visually confirm that B2F is working. Files will be saved normally. How do I use AmigaDOS wildcard patterns? ---------------------------------------- Instead of trying to explain them, I'll just give some common patterns as examples you can use or alter: #?.iff Only filenames ending in '.iff' #?(.iff|.jpeg) Only filenames ending in '.iff' or '.jpeg' The vertical bar '|' (shift \) means OR. [a|f]#? Only files starting with 'a' or 'f' [a-g]#? Files starting with 'a' through 'g' (a, b, c, d, e, f, or g) (a|s[t])#? Files starting with 'a' or 'st' ([a-b]|c[a-o])#? Files starting with 'a' through 'co' ~(#?.(bak|info|nail)) No files ending in '.bak' or '.info' or '.nail' I know some of these look impossibly cryptic, but they can come in handy sometimes. If you enter them in the PATTERN field in the SOURCE PATH FILE REQUESTER, you can see which files are being included or excluded, so experiment. If not, you can always just make sure the source directory contains only the files you want to process. What are some of the program's limitations? ------------------------------------------- String gadgets vs. Text gadgets in B2F complex requester. It may at first appear confusing to have text entry gadgets for display only; where entered text is not accepted. The reason I chose to do it this way is because string gadgets handle long strings better, so long file path names and such can be seen by clicking in the text gadget and scrolling with the right cursor key. Requester field async. As explained above, there is no way string or text gadgets can be updated to show choices made in their related file requesters or cycle gadgets. Other save formats (arguments) If your save format of choice requires arguments, you will probably be required to supply them for each file before it is saved. I added the routine to allow setting a JPEG quality one time only, but have not tried to cover other situations. If you have an urgent need to have another saver supported in this way, then email me at the address below and I'll add the function. File or directory names with embedded spaces * Do NOT use directories or files with names that have spaces. * Parsing some IFX return values is a pain if extra spaces are involved. I could probably program around this limitation, but it would be more trouble than it's worth. Error messages for large files I've found that, occasionally, very large files will not load into ImageFX, apparently because of memory limitations. If this is a recurring problem for you, email me and I'll see if I can find a workaround. Where do I reach the author? ---------------------------- Ross Fenmore Light Source Video & Graphics rfenmore@netcom.com