panCanvas v1.04 Documentation November 28, 1996 ----------------------- History: -------- v1.04 -- Minor change to the way brush coordinates were calculated. Previously caused some jerkiness. v1.02 -- Fixed a stupid bug that would crash the script if the center of the marquees were on either the same X or Y axis. -- Fixed a bug that prevented proper function if the marquees were centered on one another. -- Removed a little known 'check' routine that would prevent the script from working if the marquees were too close together relative to the number of frames. -- Discovered how goofy the ease routine is. It should function reasonably well if the marquees are reasonably far apart (hence the name 'pan'), but it becomes useless when the centers of the marquees are very close to each other. Until I work out an entirely new and intelligent math routine for calculating the ease factors you will have to experiment to see what you can get away with. The post processing part also gets equally screwed up when the marquees are close to one another. Currently the post routine uses motion-blur to clean up the jerkiness of the panned frames. But as the action changes from a true pan to a zoom the script will have to know to change from motion-blur to radial-blur. That will be a trick. v1.00 -- Renamed to 'panCanvas' -- Added 'rexxTricks.library' for better manipulation -- Altered the 'post.config' output a bit for proper blur distances when using the 'ease' function -- Only opens on the WorkBench now. -- Fixed problem of having to manually set the render functions when creating the 'foreign' display picture. -- Added the ability to adjust the number of colors to match the WorkBench v0.96 -- Resizing of marquee added back in. v0.94 -- Almost a complete rewrite. All position references are now made from the center of the marquees instead of the top left corner. -- An "ease-in, ease-out" utility has been added. It lets you set an ease factor to the beginning, end, or both of the sequence. -- There should no longer be a jump between the last and second-to-last frames. Fixed the way frame-steps were calculated. Rounding of the frame-step was improperly calculated before, resulting in a minor error that compounded as the sequence progressed. -- !IMPORTANT! Resizing the marquees is temporarily disabled. v0.91 -- Fixed a silly bug that mis-scaled the end-marquee v0.9 -- Fixed an offset problem in the working window. What you saw was not what you got! AGA Version got a few extra message displays just to remind you that it hadn't locked up while processing large images. -- Fixed an error-checking problem that allowed the user to choose a new marquee size that would run off the bottom of the window. v0.8 -- Added 'zooming' while panning. -- Writes out a config file to be used with 'pan_post' -------- Requirements: This program is RAM and CPU intensive. If you output full video frames, the original image is probably going to be quite large. A fast processor is a must. Although it has been tested on an A1200, for practical usage, an Amiga with a graphics card running CyberGraphX software is highly recommended. A 256-color oversized (800x600 or higher) WorkBench is also highly recommended. -------- Description: 'panCanvas' sets up a user-friendly, WYSIWYG interface for the creation of 'panned' sequences across a static background. It lets the user see exactly the starting area and the ending area. User can set total frames, ease-in and ease-out for each sequence, and even scale the start and end frames for a simultaneous zoom while panning. 'panCanvas' creates a custom interface window on the 'WorkBench'. This window contains a scaled version of the main buffer image. All actions take place on the 'pan' window. Two 'frame' marquees appear on the 'pan' window with frame numbers in the top-left corners. One will always say '1' to indicate the start-frame; the other will display the last frame number as set by the user -- initially it is set to '2'. The size and aspect ratio of the frame-marquees reflect the output frame size as defined by the user, and their relative 'real-size' compared to the main buffer. The interface is WYSIWYG. The marquees represent exactly what will be included in the first and last frame respectively. A 'rubber-band' line attached to their centers gives some idea of the direction of the pan. The frame-marquees can be moved anywhere within the 'pan window' but not outside of it. -- Setting and Swapping start and end frames When the user sets the frame number the number in the top left corner of the second frame marquee will change to reflect the change. The 'Swap Start & End' function in the project menu allows the user to switch the start and end frames. This makes it easy to pan from point 'A' to 'B' to 'C', etc., etc. When selecting a marquee to move, the last-frame marquee always takes presidence over the first-frame marquee. This can lead to a problem if you have set the last-frame marquee to its desired position and it happens to cover the first marquee. To be able to move the first marquee without disturbing the last one, swap them temporarily, making the first one the last and the last one the first. Now you can move the other marquee. Once you are done, swap them again. -- Scaling the Marquee The marquee may be enlarged or reduced by means of the menu option labled 'Scale End Frame'. The frame size being saved always remains the same, as defined at the start. The effect of scaling the marquee is to apply a zoom while panning. The number entered becomes the new frame width. The new height is automatically calculated according to the original aspect ratio. -- Post Processing The frames are 'pixel-perfect' clips. This can cause some jitter depending on the relative distance between each frame (frame-step). A post-processing feature has been added to alleviate this effect. 'panCanvas' writes a config file for each sequence of frames it produces. This config file contains the prefix name for the frames, the total number frames, the angle of the pan, and the frame-step in pixels. A second script called 'panPost.ifx' reads this config file and produces a second, modified set of frames with a user-definable motion blur. The amount of blur (blur length) is set by the user as a percentage of the frame-step as indicated by the config file. Allowing the user to post-process rather than applying the effect while panning was deemed an advantage. The final effect is very subjective, and rather than redoing the entire pan, simply reapplying a different value to the post-process preserves the original frames for this and other post-processing functions that might come down the road. IMPORTANT! The current implementation only has an effect when doing a 'real' pan, not just a zoom. That is, there must be a reasonable amount of pixels traversed by each frame. -- Ease-in and Ease-out Ease-in and ease-out brings up a window with a graph. The graph represents the relative slope of 'frame-step' to number of frames. Initially the slope is a straight line, indicating that the frame step is the same for every frame. The buttons below the graph set the value for ease-in, ease-out, or both. That is, you may choose to ease in only, leaving the remaining sequence linear. This would be necessary if this sequence were to be tacked on to the front of another sequence (you would probably want the speed of the pan to remain constant where the two sequences were spliced together). The 'ease-factor' determines the steepness or degree of the ease. It toggles between 1 and 7. These numbers are arbitrary. The graph has no real significance other than giving some impression of the value of the 'ease'. Once you are satisfied with the setting, select the upper left 'close-gadget' of the window to exit. Your settings are stored in a config file that will be read when the panning sequence is initiated. IMPORTANT! The current implementation only has an effect when the marquees are relatively far apart. I hope to fix this in the near future. *********************************** Included: ImageFx:rexx/ launchPanCanvas.ifx -- use to start panCanvas.ifx ImageFx:rexx/ext_tools/ panCanvas.ifx -- must be launched with 'launchPanCanvas.ifx' panPost.ifx -- applies motion blur to frames panEase.ifx -- sets 'ease-in' and 'ease-out' factors; called from within panCanvas.ifx Place these in the 'ext_tools' subdirectory of 'ImageFx:rexx/'. Do not place them out in the open with the other '.ifx' files. libs: rexxsupport.library rexxmathlib.library rexxarplib.library rexxtricks.library Place these libraries in your assigned LIBS: directory. c: qsort A sorting utility necessary for some functions *********************************** Caveats: I think I've eliminated the major bugs. Since I don't have any type of video editing system I've only been able to test it using smaller frame sizes and converting them to Amiga anim format. I must rely on others to test it properly. There is currently no elegant way to abort the process once started. You can however go to a shell and type "hi". This will abort all ARexx scripts currently running. Doing this will probably leave one or more stray windows on the screen. You can close them, from a shell, like this: rx "closewindow(panhost)" <- this closes the panCanvas window rx "postmsg()" <- this closes any message windows left open The ease-in and ease-out feature is currently very rudimentary. The math is pretty goofy. The fix for it is in my head but, it may be a while before I ever get around to implementing it. If anyone else wants to fix it you're welcome. *********************************** How it works: 1) Load the background image into the main buffer. 2) Select 'Rexx' and select 'launchPanCanvas.ifx'. 3) The WorkBench screen will pop to the front. 4) From here you will be presented with three successive requestors. Enter the width and height of the output frames. 'panCanvas' will check to make sure you haven't entered illegal values. This includes non-numeric characters and a framesize that is larger than the main buffer dimensions. It is up to the user to determine that 'legal' sizes are appropriate for the effect. But, you will see that soon enough when the 'pan' window comes up. You must also choose the total colors for the 'pan' window according to your WorkBench setup. Selecting more colors than your WorkBench may cause a system CRASH! The color value you choose here is for the work image only. All frames are saved as 24-bit images. 5) 'panCanvas' will now copy the main buffer to swap temporarily. The main buffer image is scaled to fit within the maximum constraints of the 'pan' window. A reduced-color render is created and saved to ram:. 6) The 'pan' window will load the rendered image as the 'work' image. Two frame marquees appear on the 'work' image attached at their centers with a 'rubber-band' line. In the top-left corner of each frame-marquee is the start-frame number (always 1) and the end-frame number respectively. The end-frame number reflects the current status of 'total frames' as set by the user. The numbers are guides to let you know in which direction the pan is going. 7) Use the right mouse-button to access the 'project' menu options. Here you set the total number of output frames, output path, and frame prefixes. The actual frame names use the prefix and append them with '.nnnn'. The 'start' option starts the whole process. Numerous checks are made within each menu option to assure that no illegal entries have been made, or that necessary parameters have been missed. 'Start' will flag the errors, refusing to proceed until all parameters are properly set. NOTE: frame names can be any alpha-numeric character including '_' and '-'. 8) The 'options' menu allows grid-snap options to be set. 'X-lock' allows movement of the frame-outlines only in the Y-plane. 'Y-lock' allows movement only in the X-plane. The grid-snap option allows the user to set an incremental x/y snap using a list of predetermined vales. Because of the way the numbers are rounded, relative to the 'real' size of the main buffer, the values that appear in the status window are a bit goofy. But, they are consistant. Use grid snap if you want to pan around an image and end up at the exact start position (for a looped pan). 9) Once all parameters are set, selecting 'Start' will initiate the process. A status message is displayed in the upper left corner. Currently there is no abort option. ************************************ Ola Eric Olsson email: oeolsson@tmisnet.com November 28, 1996