TSMorph 3.0 � 1993 Topicsave Limited/M J Paddock

TSMorph 3.0 Contents

@Remark $VER: TSMorph_guide 3.0 (5.3.94)

@HTMLOFF

1 Quick overview

For a quick tutorial see @{"Tutorial/Tutorial.readme" ALINK "Tutorial/Tutorial.readme/Main"}.

TSMorph is a set of morphing programs. It consists of two programs:

TSMorph         Edit the Morph parameters
TSMorph-render  Generate the morphed images

TSMorph is used to create a parameter file which is used by TSMorph-render to produce the morphed images. TSMorph-render works with 24 bit internally. Run times can be about 3 seconds per frame for a 150x150 image on a 28Mhz 68040 - See Benchmarks.

TSMorph-render can be used to morph one image to another in a set number of frames with a number of control points, just distort one image with control points. It can also be used to morph or warp a series of images (e.g. to morph between two animations). When TSMorph is run without parameters it will display an ASL file requester for a file created by TSMorph, it will then create the images, displaying a Progress Requester on the default (or named) public screen allowing the process to be interrupted and/or stopped.

ARexx scripts are run before and after each image is processed, and also before each image is loaded. These allow the changing of movement and colour to be controlled along with the ability to only generate some frames, and also pre and post image processing (e.g. to change to a non-24-bit format and build an animation).

TSMorph is used to generate the parameter file. When run it displays an Information Window on a public screen. This allows the input of the file names to morph between, the number of frames, the start frame, the output file names, and the type of morph (single or dual images) to be changed.

It also allows the editing of control points on the images. The images (most image formats can be loaded - See OPENMODE) are displayed on a public screen in resizeable, scrollable windows.

When the images are displayed control points can be edited in various modes. These modes allow the addition, deletion, linking and unlinking of the control points.

Context sensitive help is displayed using amigaguide (if available). The Help key can be pressed in the gadgets, over the gadgets, on menus or anytime a window is active.

TSMorph is �1993/94 Topicsave Limited.

The author can be contacted by EMail as mark@topic.demon.co.uk or mpaddock@cix.compulink.co.uk.

2 Installation instructions

If you wish to use Installer then TSMorph can be installed using the supplied script. If not then the following is a description of what the script does.

• 1) Make a new drawer for the executables - default Work:TSMorph,
• 2) Copy TSMorph, TSMorph-render, TSMorph.doc, TSMorph.guide, TSMorph-prefs and the Rexx drawer and its contents and all their icons to the drawer created in 1) above (if you have a 68020/030 with 68881/2 then copy the FPU version TSMorph-render.881 and rename it as TSMorph-render instead of copying TSMorph-render, or if you have a 68040 then copy the 040 version TSMorph-render.040 and rename it as TSMorph-render instead of copying TSMorph-render)
• 3) If required copy the Brush and Cursor drawers and contents.
• 4) Make new drawers ENVARC:TSMorph and ENV:TSMorph,
• 5) Copy the default Icons to the directories created above.
• 6) Amend your s:user-startup to assign TSMorph: to the drawer created in step 1).
• 7) Manually perform the assign in step 6).
• 8) If you are running system version 3.0 (or greater) change the default tool for TSMorph.guide to MultiView.
• 9) If required copy the Tutorial directory to TSMorph:.
• 10) If required copy the HTML directory to TSMorph:, also copy the View_HTML icon and use an editor to make the file contain:

    CD HTML
    Path:Mosaic file://localhost/TSMorph:html/TSMorph.html

        Where Path:Mosaic is the location of your version of Mosaic.

The following files are included in this distribution:

COPYING                      GNU General Public License
TSMorph-render.881           The rendering program 68020/68881 version
TSMorph-render.881.info      Icon
TSMorph-render.040           The rendering program 68040 version
TSMorph-render.040.info      Icon
TSMorph                      The parameter set up program
TSMorph.info                 Icon
TSMorph-prefs                Preferences editor
TSMorph-prefs.info           Icon
TSMorph-render               The rendering program
TSMorph-render.info          Icon
@{"TSMorph.doc" ALINK "TSMorph.doc/Main"}                 Documentation in plain text format
TSMorph.doc.info             Icon
@{"TSMorph.guide" ALINK "TSMorph.guide/Main"}               Documentation in amigaguide format
TSMorph.guide.info           Icon
Install                      Installation script for Installer
Install.info                 Icon
Installer                    Commodore Installer
Read.Me                      Short read me file
Read.Me.info                 Icon
View_HTML.info               Icon
HTML/#?                      .html files
HTML/Images/#?               .html images
Env.info                     Icon
Env/TSMorph.info             Icon
Env/TSMorph/def_points.info  Default project Icon
Env/TSMorph/def_bw16.info    Default 16 colour grey Icon
Env/TSMorph/def_bw256.info   Default 256 colour grey Icon
Env/TSMorph/def_ham6.info    Default HAM 6 Icon
Env/TSMorph/def_ham8.info    Default HAM 8 Icon
Env/TSMorph/def_dctv3.info   Default DCTV 3 plane Icon
Env/TSMorph/def_dctv4.info   Default DCTV 4 plane Icon
Env/TSMorph/def_iff.info     Default OpalVision IFF Icon
Env/TSMorph/def_ilbm.info    Default 24 bit ILBM Icon
Env/TSMorph/def_jpg.info     Default OpalVision JPEG Icon
Env/TSMorph/def_ppm.info     Default PPM Icon
Env/TSMorph/def_prefs.info   Default prefs Icon
Rexx.info                    Icon
@{"Rexx/FadeToBlack.TSM" ALINK "Rexx/FadeToBlack.TSM/Main"}        Example prescript script
Rexx/FadeToBlack.TSM.info    Icon
@{"Rexx/FadeToWhite.TSM" ALINK "Rexx/FadeToWhite.TSM/Main"}        Example prescript script
Rexx/FadeToWhite.TSM.info    Icon
@{"Rexx/Loadscript.TSM" ALINK "Rexx/Loadscript.TSM/Main"}         Example loadscript script
Rexx/Loadscript.TSM.info     Icon
@{"Rexx/PixelMorph.TSM" ALINK "Rexx/PixelMorph.TSM/Main"}         Example prescript script
Rexx/PixelMorph.TSM.info     Icon
@{"Rexx/PixelWarp.TSM" ALINK "Rexx/PixelWarp.TSM/Main"}          Example prescript script
Rexx/PixelWarp.TSM.info      Icon
@{"Rexx/PostAnim.TSM" ALINK "Rexx/PostAnim.TSM/Main"}           Example postscript script
Rexx/PostAnim.TSM.info       Icon
@{"Rexx/Postscript.TSM" ALINK "Rexx/Postscript.TSM/Main"}         Example postscript script
Rexx/Postscript.TSM.info     Icon
@{"Rexx/PreAll.TSM" ALINK "Rexx/PreAll.TSM/Main"}             Example prescript script
Rexx/PreAll.TSM.info         Icon
@{"Rexx/PreAnim.TSM" ALINK "Rexx/PreAnim.TSM/Main"}            Example preview script
Rexx/PreAnim.TSM.info        Icon
@{"Rexx/Prescript.TSM" ALINK "Rexx/Prescript.TSM/Main"}          Example prescript script
Rexx/Prescript.TSM.info      Icon
@{"Rexx/Preview.TSM" ALINK "Rexx/Preview.TSM/Main"}            Example preview script
Rexx/Preview.TSM.info        Icon
@{"Rexx/ToHam.TSM" ALINK "Rexx/ToHam.TSM/Main"}              Example postscript script
Rexx/ToHam.TSM.info          Icon
Tutorial.info                Icon
@{"Tutorial/cat.pic" ALINK "Tutorial/cat.pic/Main"}            Cat IFF image
@{"Tutorial/girl.pic" ALINK "Tutorial/girl.pic/Main"}           Girl IFF image
@{"Tutorial/Tutorial.readme" ALINK "Tutorial/Tutorial.readme/Main"}    Tutorial instructions
Tutorial/Tutorial.readme.infoIcon     
Brush.info                   Icon
Brush/1st                    Brush
Brush/1st.info               Icon
Brush/Add                    Brush
Brush/Add.info               Icon
Brush/Del                    Brush
Brush/Del.info               Icon
Brush/Goto                   Brush
Brush/Goto.info              Icon
Brush/Last                   Brush
Brush/Last.info              Icon
Brush/Link                   Brush
Brush/Link.info              Icon
Brush/Next                   Brush
Brush/Next.info              Icon
Brush/None                   Brush
Brush/None.info              Icon
Brush/one                    Brush
Brush/one.info               Icon
Brush/Prev                   Brush
Brush/Prev.info              Icon
Brush/Rel                    Brush
Brush/Rel.info               Icon
Brush/Two                    Brush
Brush/Two.info               Icon
Brush/Unlink                 Brush
Brush/Unlink.info            Icon
Cursor.info                  Icon
Cursor/XAdd                  Pointer
Cursor/XAdd.info             Icon
Cursor/XDel                  Pointer
Cursor/XDel.info             Icon
Cursor/XL1                   Pointer
Cursor/XL1.info              Icon
Cursor/XL2                   Pointer
Cursor/XL2.info              Icon
Cursor/XMov                  Pointer
Cursor/XMov.info             Icon
Cursor/XOne                  Pointer
Cursor/XOne.info             Icon
Cursor/XRel                  Pointer
Cursor/XRel.info             Icon
Cursor/XTwo                  Pointer
Cursor/XTwo.info             Icon
Cursor/XU1                   Pointer
Cursor/XU1.info              Icon
Cursor/XU2                   Pointer
Cursor/XU2.info              Icon

3 Software and Hardware required

The following libraries (with minimum version) are required to run TSMorph:

intuition.library        37
iffparse.library         37
graphics.library         37
layers.library           37
gadtools.library         37
asl.library              37
utility.library          37
diskfont.library         36
icon.library             37
rexxsyslib.library       0

The following will also be used if present:

amigaguide.library       34
dctv.library             3
opal.library             0  Note: OpalVision board is not required
reqtools.library         38 reqtools is �1991/1992 Nico Fran�ois
                            This is required for Animated Warps/Morphs
nofrag.library           2  nofrag is � Copyright 1991 Jaba Development.
egs.library              0  EGS is � Copyright 1990/93 VIONA Development.
egsintui.library         0
egsgfx.library           0
egsrequest.library       0

TSMorph-render requires a large amount of chip memory (or opal.library). If you have 1Mb then 512x512 images can be morphed (though you may have to run workbench on a 2 colour 640x200 screen). 640x512 is probably impossible without 2Mb of chip memory.

The amount of chip memory required by TSMorph can be reduced to 1/5 by setting the ZOOM parameter to OFF.

4 Tool types and Shell parameters

Both TSMorph and TSMorph-render can be run from the Shell or the Workbench. Most parameters can be edited using the Settings menu.

Note: TSMorph and TSMorph-render both require a stack size of more than 4096. 8192 should be OK. If the stack is not set large enough then the programs will probably just crash.

Parameters can be supplied, normally either on the Shell command line, as Icon Tool Types on the Project, TSMorph or TSMorph-render Icon, or in a settings file.

The format of settings files is a text file with lines in the format:

Settingstype=settingsvalue

Blank lines or lines starting with a ; (semi-colon) are treated as comments. Any settings supplied on the Shell command line or as an Icon Tool Type override values specified in this file. Parameters on the Project Icon override parameters on the Tool Icon.

Note: All the Project Icon tool types are used if the project is run with a default tool or by double clicking a tool, some are not used if the project is selected using a file requester, if the Tool was run from the Shell then file requester selected project tool types are ignored. Also some settings can not be changed on open projects,

The Settings file name used is first file found from:

1) The name supplied in the SETTINGS= parameter on the project.
2) The name supplied in the SETTINGS= parameter on the tool.
3) TSMorph.prefs
   in the project directory for the workbench,
   the current directory from the Shell.
4) TSMorph.prefs
   in the directory TSMorph was loaded from.
5) ENV:TSMorph/TSMorph.prefs

Unless KEEPSETTINGS is set to NO current settings are saved in ENV:TSMorph/TSMorph.prefs when TSMorph is quit. Settings can be saved and loaded from the Settings menu.

Parameters to TSMorph

The following parameters can be supplied, normally either on the Shell command line, as Icon Tool Types on the Project or TSMorph Icon, or in a settings file:

CHANGEPALETTE=YES/NO/OFF

Sets the default value of the Change Palette? settings menu item - defaults to YES.

This item toggles if each images palette should be used to display the image when the window is active. Each image window can have its own palette. This option operates with the OPENMODE parameter.

Since the ability to change screens colour palettes is not supported by CBM this menu option can be disabled by setting this parameter to OFF.

CREATEICONS=YES/NO

Sets the default value of the Create Icons? settings menu item - defaults to YES.

This item toggles if Icons are to be saved with parameter files. If it is selected then an Icon will be saved. The icon will come from ENV:TSMorph/def_points if this exists, secondly from ENV:SYS/def_points, otherwise the default project Icon is used.

This parameter is not changed by Requester loaded projects.

CREATEICONSP=YES/NO

Sets the default value of the Create Prefs Icons? settings menu item - defaults to YES.

This item toggles if Icons are to be saved with Settings files. If it is selected then an Icon will be saved. The icon will come from ENV:TSMorph/def_prefs if this exists, secondly from ENV:SYS/def_prefs, otherwise the default project Icon is used.

CUSTOMDEPTH=4

This gives the depth of the custom screen to open if CUSTOMMODE is specified.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the screen mode, but any change is ignored until TSMorph is reloaded.

The default value is 4.

CUSTOMMODE=screen_mode

This gives the mode of the custom screen to open.

The mode is as show in the Screen Mode requester - case is ignored (e.g. "PAL:Low Res"). This parameter is not changed by Requester loaded projects.

The name of the screen must be given by the PUBSCREEN parameter. The depth is given by the CUSTOMDEPTH parameter. The screen will mostly clone the Workbench, but other colours will be set up as a grey scale.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the screen mode, but any change is ignored until TSMorph is reloaded.

The default value is nothing which means do not open a custom screen.

EGS=YES/NO

This controls the use of EGS when displaying the edit windows. See requirements for library requirements. If set to yes then the edit windows and relevent error requesters are displayed on the default EGS screen.

ZOOM is always set to OFF when using EGS. OPENMODE may also be ignored in some circumstances.

This parameter is not available as a menu option, is not saved in settings files and can not be specified on a project Icon.

Default values is NO.

FILES=filename

This is only relevant to the Shell, only one name can be supplied - default is to open a new unnamed project.

HELP=YES/NO

Sets the default value of the Continuous Help? settings menu item - defaults to NO.

This option has more effect when running release 3.0 or later. When set to YES help is continuously displayed using amigaguide (if available).

KEEPSETTINGS=YES/NO

Sets the default value of the Keep Settings? settings menu item - defaults to YES.

By default current settings are saved in ENV:TSMorph/TSMorph.prefs when TSMorph is quit. This parameter and menu item enable this behaviour to be turned off.

OPENMODE=ALWAYS/IFILBM/IFCOLOURS/REMAP/OPAL

This parameter and menu item specify how images should be loaded for displaying by TSMorph.

• ALWAYS - Only try and load normal ILBM images. Fail if not. The CHANGEPALETTE parameter has an affect on the image display.
• IFILBM - First try to load as an ILBM image, load and remap the image if the image is not an ILBM or has 24 planes.
• IFCOLOURS - As IFILBM but remap if the number of planes in the image exceed the number of the screen.
• REMAP - Loads most ILBM (including 24 bit, EHB, HAM6, HAM8 and DCTV (with dctv.library [REMAP needs to be specified to correctly display DCTV images]), JPEG, TARGA, PPM and GIF. For JPEG if CHANGEPALETTE=YES or NO and the screen (see PUBSCREEN) has more than 2 bit planes then the image is remapped to a dynamic type palette. Otherwise the image is remapped to the screen palette. If this fails then opal.library will be used (if present). This may be required for some JPEGs.
• OPAL - Always use opal.library to load the image. This is probably only useful to load images in Opal FAST IFF format. The images are remapped to the current palette.

When loading and remapping complex images a requester is displayed with a title of Loading Image, a text gadget giving progress messages, a Pass gadget, and a third progress gadget. There is no way of interrupting the load process.

For slow machines it is suggested that you convert the images to ILBMs and specify ALWAYS.

PREVIEW=scriptname

This specifies the name of an ARexx script to run to preview the rendered image.

The default script is @{"Rexx/Preview" ALINK "Rexx/Preview.TSM/Main"}.

The version supplied renders the image as a 16 colour grey scale with a resolution of about 128/64 and displays it.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

PUBSCREEN=pubscreenname

This gives the name of the Public Screen on which to open all TSMorph windows - default is the default public screen.

This parameter is not changed by Requester loaded projects.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the screen name, but any change is ignored until TSMorph is reloaded.

If CUSTOMMODE is supplied as well then a public screen of this name is opened.

REQTOOLS=YES/NO/ALL

This controls the use of reqtools.library. If set to NO then reqtools will not be used (except in very unusual circumstances). It will still however be opened and closed. If set to YES then reqtools will be used for various requesters. If set to ALL then it will be used for the File Requesters as well.

This parameter is not available as a menu option, is not saved in settings files and can not be specified on a project Icon.

Default values is YES.

SETTINGS=filename

This can only be supplied on the Shell command line, or an Icon Tool Type. It specifies the name of a file for more parameters. See section parameters.

This parameter is not changed by Requester loaded projects.

ZOOM=YES/NO/OFF

Sets the default value of the Zoom? settings menu item. If set to YES then images will be initially displayed 2x normal size, if set to NO then images will be initially displayed normal size, setting to OFF disables the Zoom? option, this reduces chip memory usage to 1/5 - defaults to NO.

Parameters to TSMorph-render

The following parameters can be supplied, normally either on the Shell command line, as Icon Tool Types on the Project or TSMorph-render Icon, or in a settings file:

ANTIALIAS=NO/YES

This parameter and menu item select if the output files should be Anti-Aliased. Setting to YES can improve the quality of the images but will slow down the rendering process.

This parameter is ignored if INTEGER is set to YES.

Default value is NO.

CREATEICONSR=NO/YES

This parameter and menu item selects if Icons are to be saved with image files. If it is YES then an Icon will be saved. The icon depends on the save format.

ENV:TSMorph/def_bw16  - 16 colour grey scale images
ENV:TSMorph/def_bw256 - 256 colour grey scale images
ENV:TSMorph/def_ham6  - HAM 6 images
ENV:TSMorph/def_ham8  - HAM 8 images
ENV:TSMorph/def_dctv3 - DCTV 3 plane images using dctv.library
ENV:TSMorph/def_dctv4 - DCTV 4 plane images using dctv.library
ENV:TSMorph/def_iff   - 24 bit ILBM saved using opal.library
ENV:TSMorph/def_ilbm  - 24 bit ILBM saved without opal.library
ENV:TSMorph/def_jpg   - JPEG files saved using opal.library
ENV:TSMorph/def_ppm   - PPM files

If the file does not exist then ENV:SYS/def_ilbm (etc.) is tried, if this does not exist then the default project Icon is used.

Default value is NO.

DEPTH=number

This parameter indicates how deep the Morphing algorithm should search to find the points to use for morphing. The maximum value is 20 (higher values are accepted but will be taken as 20).

Default value is 2.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

DX=number

This parameter can be used to speed up the rendering process. The default value is 0.

If set to a number then only some Horizontal pixels will be generated. e.g. if set to 3 then only every 4th pixel will be generated. The others will be copied from the previous pixel. This can be overridden by using ARexx. Also see DY.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

DY=number

This parameter can be used to speed up the rendering process. The default value is 0.

If set to a number then only some Vertical pixels will be generated. e.g. if set to 1 then only every other line will be generated. The others will be copied from the previous line. This can be overridden by using ARexx. Also see DX.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

EGS=YES/NO

By default TSMorph-render does not show its output when rendering. If this parameter is set to YES then output will be displayed in an EGS window on the default EGS screen a line at a time. See requirements for library requirements.

This parameter is not available as a menu option, is not saved in settings files and can not be specified on a project Icon.

Default values is NO.

FILES=filename

This is only relevant to the Shell, only one name can be supplied - default is to show an ASL file requester for the file to run.

INTEGER=NO/YES

This parameter and menu item select if the render process should use integer or floating point arithmetic. The process will be faster if integer arithmetic is used (especially on machines without an FPU). However the output quality will not be so good.

If this parameter is set to YES then the ANTIALIAS parameter is ignored.

Default value is NO.

LOADSCRIPT=Scriptname/OFF

This specifies the name of an ARexx script to run before each image 24 bit image is loaded. This can be used to e.g. hold the images on disc in JPEG format to save space and convert each image back to 24 bit ILBM when required. Note however that TSMorph-render now has the ability to load a large variety of image formats (All ILBM including HAM6, HAM8, EHB, and DCTV with dctv.library, JPEG, TARGA, PPM, and GIF).

The default script is @{"Rexx/Loadscript" ALINK "Rexx/Loadscript.TSM/Main"}.

The version supplied does nothing.

Set to OFF to run no script.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

MODE=0-31

This parameter and menu item indicate how the Morphing algorithm should search to find the points to use for morphing.

The values are additive:

   1 : Leaves un-triangled point stationary
   2 : Searches all the closest points
   4 : Uses a squaring algorithm to find close points
   8 : Uses a Delaunay algorithm to find triangles
   16: Precalculate close points

Default value is 0.

POSTSCRIPT=Scriptname/OFF

This specifies the name of an ARexx script to run after each image is rendered. This can be used to build an animation or change the image format from 24 bit.

The default script is @{"Rexx/Postscript" ALINK "Rexx/Postscript.TSM/Main"}.

The version supplied does nothing.

Set to OFF to run no script.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

PRESCRIPT=Scriptname/OFF

This specifies the name of an ARexx script to run before each image is rendered. This can be used to produce only some of the frames and control the movement and colour of the images.

The default script is @{"Rexx/Prescript" ALINK "Rexx/Prescript.TSM/Main"}.

The version supplied does nothing.

Set to OFF to run no script.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

PUBSCREENR=pubscreenname

This gives the name of the Public Screen on which to open TSMorph-render windows - default is the default public screen.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the screen name.

QUALITY=number

This specifies the quality of output files. This option only applies if opal.library is available and SAVEFORMAT is JPEG or JPEGT. Possible values are 0 to 100.

Default value is 75.

It can be changed using the menu item (if reqtools.library is available), a requester is displayed allowing the input of the value.

REQTOOLS=YES/NO/ALL

This controls the use of reqtools.library. If set to NO then reqtools will not be used (except in very unusual circumstances). It will still however be opened and closed. If set to YES then reqtools will be used for various requesters. If set to ALL then it will be used for the File Requesters as well.

This parameter is not available as a menu option, is not saved in settings files and can not be specified on a project Icon.

Default values is YES.

SAVEFORMAT=ILBM24/OPAL24/OPAL24T/OPAL24F/OPAL24FT/JPEG/JPEGT/PPM/BW16/BW256/HAM6/HAM8/DCTV3/DCTV4

This parameter and menu item specify the format TSMorph-render should use to save the output images. OPAL and JPEG formats are only available if opal.library is available. DCTV3 and DCTV4 formats are only available if dctv.library is available.

ILBM24   - IFF 24 bit ILBM with no CAMG chunk
OPAL24   - IFF 24 bit ILBM saved using opal.library
OPAL24T  - as OPAL24 with a Thumbnail
OPAL24F  - as OPAL24 in Fast Format
OPAL24TF - as OPAL24F with a Thumbnail
JPEG     - JPEG format using opal.library
JPEGT    - as JPEG with a Thumbnail
PPM      - PPM format
BW16     - ILBM 16 colour grey scale
BW256    - ILBM 256 colour grey scale
HAM6     - ILBM 6 plane HAM
HAM8     - ILBM 8 plane HAM
DCTV3    - ILBM 3 plane DCTV using dctv.library
DCTV4    - ILBM 4 plane DCTV using dctv.library

The quality of JPEG images can be set using the QUALITY parameter.

PPM format is basically uncompressed 24 bit. The files are therefore very large and it is suggested that a compressing file handler (such as XFH or EPU) is used. This format is provided mainly to allow the easy production of MPEG movies.

The save format also controls which Icon is saved with the image.

SETTINGS=filename

This can only be supplied on the Shell command line, or an Icon Tool Type.

This specifies the name of a file to contain settings. See section parameters.

TOOLPRI=number

This can only be supplied as a Tool Icon tool type. It sets the priority of the rendering process.

Setting to -1 is a good idea if you wish to run the program in the background. The default value is 0. Setting to positive values is generally not a good idea.

5 The Information Window

This window is always displayed when TSMorph is running. It displays information about the current project. The window title is TSMorph, the screen title will be displayed as the project name if the project has a name. It is used to set up all the information required by TSMorph-render.

Gadgets in Info Window

@font topaz.font 8 The Information Window appears with gadgets:

@HTML <img src="Images/Info"><P> @HTMLOFF

-----------------------------
|.|TSMorph           |�|�|
|---------------------------|
|��������Help Text���������|
| File @{u}O@{uu}ne ............. X|
| File @{u}T@{uu}wo ............. X|
|24 File @{u}1@{uu} ............. X|
|24 File @{u}2@{uu} ............. X|
|    Width ...  Height ...|
| Single @{u}F@{uu}rames.. St@{u}a@{uu}rt .|
|     @{u}N@{uu}ame ............  X|
|������Edit Points...������|
-----------------------------

@HTMLON

Help Text gadget

This gadget displays short help messages.

From release 3.0 and up it displays more information. See also Continuous Help.

File One gadget

This gadget allows the editing of the file name of the first image to be used when editing points. This gadget is disabled if the Edit Windows are currently open. The file name can be either edited in the string gadget or by using the Get File to display an ASL file requester.

This image should be a Workbench displayable version of the first 24 bit file. (See OPENMODE for what images can be loaded.) It is displayed in the first Edit Window when editing points.

o can be used to activate this gadget - See section Keyboard.

See File naming for how to specify the file name.

Get File One gadget

This gadget displays an ASL file requester to select the file to appear in the File One gadget.

o with shift is the same as using this gadget - See section Keyboard.

File Two gadget

This gadget is the same as the File One gadget for the second displayable image. This image should be the same size as the first.

t can be used to activate this gadget - See section Keyboard.

See File naming for how to specify the file name.

Get File Two gadget

This gadget displays an ASL file requester to select the file to appear in the File Two gadget.

t with shift is the same as using this gadget - See section Keyboard.

24 File 1 gadget

This gadget allows the editing of the file name of the first image to be used when morphing. The file name can be either edited in the string gadget or by using the Get File to display an ASL file requester.

This image should be a 24 bit version of the first displayable file. Also see the LOADSCRIPT parameter. Note: TSMorph now has the ability to load a large variety of images as 24 bit files. If this gadget is left blank then the name from the first displayable file is used.

1 can be used to activate this gadget - See section Keyboard.

See File naming for how to specify the file name.

Get 24 File 1 gadget

This gadget displays an ASL file requester to select the file to appear in the 24 File 1 gadget.

1 with shift is the same as using this gadget - See section Keyboard.

24 File 2 gadget

This gadget allows the editing of the file name of the last image to be used when morphing. The file name can be either edited in the string gadget or by using the Get File to display an ASL file requester.

This image should be a 24 bit version of the second displayable file. Also see the LOADSCRIPT parameter. Note: TSMorph now has the ability to load a large variety of images as 24 bit files. If this gadget is left blank then the name from the second displayable file is used.

If Single Image mode is selected then this is ignored.

2 can be used to activate this gadget - See section Keyboard.

See File naming for how to specify the file name.

Get 24 File 2 gadget

This gadget displays an ASL file requester to select the file to appear in the 24 File 2 gadget.

2 with shift is the same as using this gadget - See section Keyboard.

Width gadget

This gadget displays the width of the images being edited. If images have not been selected then it should display the maximum width of the current points.

Height gadget

This gadget displays the height of the images being edited. If images have not been selected then it should display the maximum height of the current points.

Single image gadget

This gadget cycles between Morphs, Warps, Animated Morphs and Animated Warps.

In Warp mode one image is distorted based on the control points.

In Morph mode one image is distorted/recoloured into a second image based on control points.

In animated Warps and Morphs the input images can change on each output frame.

r and R can be used to cycle this gadget forward and backward - See section Keyboard.

Note: Animated Warps/Morphs are only available if Reqtools is available.

Number of Frames gadget

This gadget can be used to specify the number of frames to generate.

In Single mode the total number of frames will be this number plus the first image.

In dual mode the total number of frames is the first image, this number and the last image.

f can be used to activate this gadget - See section Keyboard.

This gadget is disabled if Images are displayed and an animated Morph/Warp is being edited.

Start Frame gadget

This gadget can be used to specify the number to use in the Name of the first generated file. This number is then incremented by 1 for each subsequent frame.

a can be used to activate this gadget - See section Keyboard.

This gadget is disabled if Images are displayed and an animated Morph/Warp is being edited.

Anim file Name gadget

This gadget is used to name the files produced by TSMorph-render.

The file name can be either edited in the string gadget or by using the Get File to display an ASL file requester.

The file name should contain the characters %ld. These characters will be replaced by the frame number, starting from that specified in the Start gadget.

n can be used to activate this gadget - See section Keyboard.

See File naming for further information on how to specify the file name.

Get Anim file Name gadget

This gadget displays an ASL file requester to select the file to appear in the Name gadget.

n with shift is the same as using this gadget - See section Keyboard.

Edit Points... gadget

This button gadget has the same effect as the Edit Points menu option. It opens the Control Window and Edit Windows to allow editing of the control points. If these windows are already open then the Control Window is activated.

p is the same as using this gadget - See section Keyboard.

Close gadget

This is a standard close gadget. Clicking quits the program.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Zoom gadget

This is a standard Zoom gadget which switches the window between full size and a title bar and the help text.

Depth gadget

This is a standard depth gadget.

Menus on the Info Window

The following menus are available on the Information Window:

Info Window Project menu

This menu contains the following items with their associated Amiga short-cuts in the Info Window:

Info Window Project/New menu item

This menu item creates a new project.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Info Window Project/Open menu item

This menu item allows the loading of a previously created Parameter file.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Info Window Project/Save menu item

This saves the current project using the current name. If the project does not yet have a name then an ASL file requester is displayed.

See section File Format.

Info Window Project/Save As... menu item

This saves the current project using a name chosen suing an ASL file requester.

See section File Format.

Info Window Project/Delete... menu item

This can be used to delete a Project. It will delete the main file, its icon (if present) and any associated Anim points files.

See section File Format.

Info Window Project/About... menu item

This displays some program version information in the About Requester.

Info Window Project/Quit menu item

This quits TSMorph.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Info Window Project/Preview... menu item

This menu item renders the image using the ARexx script supplied in the PREVIEW parameter.

If required it first displays the Frame Number requester.

This menu option is only available if reqtools.library is available.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Info Window Project/Edit Points menu item

This is the same as the Edit Points gadget.

It opens the Control Window and Edit Windows to allow editing of the control points. If these windows are already open then the Control Window is activated.

Keyboard controls in the Info Window

The following keyboard controls are available in the Info Window:

o  Activate File One gadget
   With shift - show file requester - See section Get File One.

t  Activate File Two gadget
   With shift - show file requester - See section Get File Two.

1  Activate 24 File 1 gadget
   With shift - show file requester - See section Get 24 File 1.

2  Activate 24 File 2 gadget
   With shift - show file requester - See section Get 24 File 2.

rR Cycle Single image gadget.

f  Activate Frames gadget.

a  Activate Start gadget.

n  Activate Name gadget
   With shift - show file requester - See section Get Name.

p  Same as Edit Points gadget

Help displays context sensitive help using amigaguide if available.

6 The Control Window

The control window displays various gadgets for different for different point editing modes. The title bar displays the current editing mode as does the Mouse pointer. The screen title bar displays TSMorph for non-animated Warps/Morphs and TSMorph - Frame nnn for animated Warps/Morphs.

Control and Image Window gadgets

@font topaz.font 8 The Control Window appears with gadgets:

@HTML <img src="Images/Contrl"><P> @HTMLOFF

--------------
|.| Mov |��|
|------------|
|�ONE��TWO�|
|�REL��ADD�|
|�DEL��LNK�|
|�UNL��MOV�|
||<<?>>||
--------------

@HTMLON

Most are used to set the edit mode. The rest except the close and depth gadgets are used to set the current Frame Number.

Control Window First Frame gadget

This gadget goes to the first frame. This is the same as the First menu item.

This gadget is disabled if the Morph/Warp is not animated, or the first frame is already displayed.

Control Window Previous Frame gadget

This gadget goes to the previous frame. This is the same as the Previous menu item.

This gadget is disabled if the Morph/Warp is not animated, or the first frame is currently displayed.

Control Window Goto Frame gadget

This gadget goes to a chosen frame. This is the same as the Goto menu item. It displays the Frame Number Requester.

This gadget is disabled if the Morph/Warp is not animated.

Control Window Next Frame gadget

This gadget goes to the next frame. This is the same as the Next menu item.

This gadget is disabled if the Morph/Warp is not animated, or the last frame is currently displayed.

Control Window Last Frame gadget

This gadget goes to the last frame. This is the same as the Last menu item.

This gadget is disabled if the Morph/Warp is not animated, or the last frame is already displayed.

Control Window Close gadget

This closes the Control Window, and the Edit Windows.

Control Window Depth gadget

This is a standard depth gadget.

Control and Edit Windows menus

The following menus are available on the Control and Edit Windows:

Control and Edit Windows Project menu

This menu contains the following items with their associated Amiga short-cuts in the Control and Edit Windows:

Control and Edit Window Project/New Points menu item

This menu item deletes all existing points.

Control and Edit Window Project/Open Points menu item

This menu item allows the loading of a previously created Parameter file.

Only the points are loaded from the file. Other parameters are retained.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Control and Edit Window Project/Save menu item

This saves the current project using the current name. If the project does not yet have a name then an ASL file requester is displayed.

See section File Format.

Control and Edit Window Project/Save As... menu item

This saves the current project using a name chosen using an ASL file requester.

See section File Format.

Control and Edit Window Project/About... menu item

This displays some program version information in the About Requester.

Control and Edit Window Project/Exit Points menu item

This is the same as closing the Control Window or either of the Edit Windows. It closes all of these windows.

Control and Edit Window Project/Quit menu item

This quits TSMorph.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Control and Edit Windows Project/Preview... menu item

This menu item renders the image using the ARexx script supplied in the PREVIEW parameter.

If required it first displays the Frame Number requester.

This menu option is only available if reqtools.library is available.

If the current project has been changed but not saved then the Unsaved Project requester is displayed.

Control and Edit Window Edit menu

This menu contains the following items with their associated Amiga short-cuts in the Control and Edit Windows:

Control and Edit Window Edit/Add Grid... menu item

This menu item displays the Add Grid requester to add a grid of points to the images.

Control and Edit Window Edit/Triangulate menu item

This menu item deletes all links between points and attempts to convert them to triangles (similar to the MODE=24 option of TSMorph-render). If the current project has been changed then the Unsaved Project requester is displayed.

Control and Edit Windows Frame sub menu

This sub menu contains the following items with their associated Amiga short-cuts in the Control and Edit Windows:

Control and Edit Windows Frame/First menu item

This menu item goes to the first frame. This is the same as the First gadget.

This menu item is disabled if the Morph/Warp is not animated, or the first frame is already displayed.

Control and Edit Windows Frame/Previous menu item

This menu item goes to the previous frame. This is the same as the Previous gadget.

This menu item is disabled if the Morph/Warp is not animated, or the first frame is already displayed.

Control and Edit Windows Frame/Goto menu item

This menu item goes to a chosen frame. This is the same as the Goto gadget. It displays the Frame Number Requester.

This menu item is disabled if the Morph/Warp is not animated, or the first frame is already displayed.

Control and Edit Windows Frame/Next menu item

This menu item goes to the next frame. This is the same as the Next gadget.

This menu item is disabled if the Morph/Warp is not animated, or the last frame is already displayed.

Control and Edit Windows Frame/Last menu item

This menu item goes to the last frame. This is the same as the Last gadget.

This menu item is disabled if the Morph/Warp is not animated, or the last frame is already displayed.

Control and Edit Window Edit/Mode sub menu

This sub menu contains the following items with their associated Amiga short-cuts in the Control and Edit Windows:

Settings menu

This menu contains the following items with their associated Amiga short-cuts in the Control, Info and Edit Windows. Settings can be set using Parameters. All menu items which display requesters will not be available if reqtools.library is not available. Items requiring opal.library will not be available if opal.library is not available.

Setting/Load Settings... menu item

This displays an ASL requester to load settings into the currently running program.

The default name is TSMorph.prefs.

Settings/Save Settings menu item

This saves the current settings in ENVARC:TSMorph/TSMorph.prefs and ENV:TSMorph/TSMorph.prefs.

If CREATEICONSP is set then an Icon is saved as well

Unless KEEPSETTINGS is set to NO current settings are saved in ENV:TSMorph/TSMorph.prefs whenever TSMorph is quit.

Setting/Save Settings As... menu item

This displays an ASL requester to save the current settings.

If CREATEICONSP is set then an Icon is saved as well

The default name is TSMorph.prefs.

Setting/Reset To Defaults menu item

This resets settings to there default values.

If some Image windows are open and CHANGEPALETTE is set to OFF then it will stay OFF. The same applies to ZOOM.

Settings/Last Saved menu item

This reset settings to the values last saved in ENVARC:TSMorph/TSMorph.prefs (overridden by any Tool Types).

If some Image windows are open and CHANGEPALETTE is set to OFF then it will stay OFF. The same applies to ZOOM.

Setting/Restore menu item

This resets settings to the values last saved in ENV:TSMorph/TSMorph.prefs (overridden by any Tool Types). Settings are saved in this file whenever TSMorph is quit if KEEPSETTINGS is set to YES.

If some Image windows are open and CHANGEPALETTE is set to OFF then it will stay OFF. The same applies to ZOOM.

Keyboard controls in the Control Window

Help displays context sensitive help using amigaguide if available.

7 The Edit Windows

The Edit windows display Workbench displayable versions of the images to be morphed along with the control points. The window title displays the file name, the screen title displays the full file name. The mouse pointer shows the current editing mode. The windows are sizeable and have scrollbars. The menus displayed are the same as the Control Window.

The first click in these windows is ignored.

If EGS is being used then the windows are displayed on the EGS screen without menus. Keyboard short cuts 1-8 are still available. The windows do not, however, automatically scroll.

Gadgets on the Edit Windows

@font topaz.font 8 The Edit Windows appears with gadgets:

@HTML <img src="Images/Image"><P> @HTMLOFF

--------------------
|.|filename |�|�|
|------------------|
|              |   |
|              ||||
|              ||||
|              ||||
|              ||||
|              |/||
|              |\||
|------------------|
|-------<-->|//|
--------------------

@HTMLON

Edit Windows Horizontal gadget

This gadget can be used to scroll the image horizontally.

Edit Windows Vertical gadget

This gadget can be used to scroll the image vertically.

Edit Windows Up gadget

This gadget can be used to scroll the image up.

Holding down shift will cause the window to scroll one pixel at a time.

Edit Windows Down gadget

This gadget can be used to scroll the image down.

Holding down shift will cause the window to scroll one pixel at a time.

Edit Windows Left gadget

This gadget can be used to scroll the image left.

Holding down shift will cause the window to scroll one pixel at a time.

Edit Windows Right gadget

This gadget can be used to scroll the image right.

Holding down shift will cause the window to scroll one pixel at a time.

Edit Windows Close gadget

This closes the Control Window, and the Edit Windows.

Edit Windows Zoom gadget

This is a standard Zoom gadget. It swaps the size between maximum and minimum

Maximum is the smaller of the size of the image or the size of the screen.

Minimum is the minimum required for all gadgets to still be visible.

Edit Windows Depth gadget

This is a standard depth gadget.

Edit Windows Sizing gadget

This a standard sizing gadget. See Zoom gadget for the sizing limits

Keyboard controls in the Edit Windows

The number keys can be used to set the Edit Mode.

Help displays context sensitive help using amigaguide if available.

8 Point editing modes

The following edit modes are available to edit points:

Note: The menu button can always be used to abort the current operation before releasing the select button.

Modes can be set using gadgets in the Control Window or by using menus on the Control and Edit Windows.

Edit Mode One

This mode is used to move a point in one of the Edit Windows.

The Control Windows title is set to One.

The Mouse Pointer is set to ONE.

Points can be clicked and moved in either of the windows with the mouse - the point will only move in the selected window.

Edit Mode Two

This mode is used to move a point in both of the Edit Windows.

The Control Windows title is set to Two.

The Mouse Pointer is set to TWO.

Points can be clicked and moved in both of the windows with the mouse - the point will move in both windows to the same absolute position.

Edit Mode Relative

This mode is used to move a point in both of the Edit Windows.

The Control Windows title is set to Rel.

The Mouse Pointer is set to REL.

Points can be clicked and moved in both of the windows with the mouse - the point will move in both windows to the same relative position.

Edit Mode Add

This mode is used to add a point in both of the Edit Windows.

The Control Windows title is set to Add.

The Mouse Pointer is set to ADD.

Points can be added in either of the windows by clicking the mouse - the point will added to both windows to the same absolute position.

Edit Mode Delete

This mode is used to delete a point in both of the Edit Windows.

The Control Windows title is set to Del.

The Mouse Pointer is set to DEL.

Points can be deleted in either of the windows by clicking the mouse - the point will deleted from both windows. Any links will also be removed.

Edit Mode Link

This mode is used to link two points in both of the Edit Windows.

The Control Windows title is initially set to L1.

The Mouse Pointer is set to L1.

A point can then be selected in either of the windows by clicking the mouse.

The Control Windows title is then set to L2.

The Mouse Pointer is set to L2.

Another point can then be selected in either of the windows by clicking the mouse. The points will be joined by a line.

Note: this line is to enable points to be identified more easily. It is not used by the rendering process.

Edit Mode Unlink

This mode is used to unlink two linked points in both of the Edit Windows.

The Control Windows title is initially set to U1.

The Mouse Pointer is set to U1.

A point can then be selected in either of the windows by clicking the mouse.

The Control Windows title is then set to U2.

The Mouse Pointer is set to U2.

Another point can then be selected in either of the windows by clicking the mouse. If the points are currently joined then the line will be removed.

Edit Mode Move

In this mode no points are edited.

The Control Windows title is set to Mov.

The Mouse Pointer is set to Mov.

Clicking in the window and moving the mouse will scroll the window.

This is the initial mode when the Edit Windows are opened.

If EGS is being used then the windows will not scroll.

9 Requesters which appear

The following requesters are produced:

Unsaved project requester

This requester is displayed when attempting to quit, preview render or triangulate without having saved a project.

It displays 3 or 4 options (depending on if amigaguide is available):

Save:    Save the project and quit, render or triangulate
Help:    Display help (only shown if available)
Abandon: Quit, preview or triangulate without saving the project
Cancel:  Do not save and do not quit, preview or triangulate

If reqtools.library(38) is available then this will be used and keyboard short-cuts (the first character of the option) will be available and underlined.

About requester

This requester is displayed when About... is chosen on a menu on the Info Window or Control or Edit Windows. It displays version information.

If reqtools.library(38) is available then this will be used and keyboard short-cuts (the first character of the option) will be available and underlined.

Error requesters

This requester is displayed if an error occurs. It displays an error message and gives one (or two) options.

If amigaguide is available then the first option will be Help - this will display detailed information on the error message.

The last option is Quit for fatal errors, and OK for non fatal errors.

See Errors for details on error messages.

If reqtools.library(38) is available then this will be used and keyboard short-cuts (the first character of the option) will be available and underlined.

If EGS is being used and the edit windows are open then the requester will appear on the EGS screen.

Add Grid requester

@font topaz.font 8 The Add Grid requester appears as below when the Add Grid... menu item is chosen

@HTML <img src="Images/AddGrid"><P> @HTMLOFF

----------------
|.|Add Grid|�|
|--------------|
| @{u}X@{uu} Cells ... |
| @{u}Y@{uu} Cells ... |
|              |
| �OK� Cancel|
----------------

@HTMLON

The following gadgets are displayed in the requester with their associated keyboard equivalents:

Add Grid X Cells gadget

This gadget is used to input the number of horizontal cells of points to add. The minimum number is 1. The default value displayed is 5.

This gadget can be activated by using the X key.

Add Grid Y Cells gadget

This gadget is used to input the number of vertical cells of points to add. The minimum number is 1. The default value displayed is 5.

This gadget can be activated by using the Y key.

Add Grid OK gadget

Selecting this gadget adds points of cells to the images. The number of horizontal cells can be set in the X Cells gadget and the number of vertical cells in the Y Cells gadget.

The O key is the same as using this gadget.

Add Grid Cancel gadget

This gadget cancels the Add Grid requester without adding any points.

The C key is the same as using this gadget.

Add Grid Close gadget

This is the same as the Cancel gadget and cancels the requester.

Add Grid Depth gadget

This is a standard depth gadget.

Choose a Frame Number requester

This requester is displayed when the Edit Points gadget is selected (and there is more than one frame) on an animated Morph/Warp, or the Goto gadget or Goto menu item is selected, or the Preview... or Preview... menu item is selected.

It displays the first and last frame number and allows input of the required frame number.

It displays OK, Help (if amigaguide is available) and Cancel gadgets. The keyboard shortcuts (O,H and C) are underlined.

Progress requester

This requester is displayed by TSMorph-render. It shows a list view of information messages, and the current frame and line being calculated.

It also displays a stop button and a zoom and depth gadget.

The stop gadget is checked every line. Clicking it displays the Really quit? requester allowing the program to be stopped.

The Help key displays help.

Really quit? requester

This requester is displayed when the stop gadget is clicked on the Progress requester. It displays two (or three) options Quit (Help) and Continue. Quit quits the program, Continue restarts the calculation, Help is displayed if amigaguide is available and displays help.

If reqtools.library(38) is available then this will be used and keyboard short-cuts (the first character of the option) will be available and underlined.

10 Changing the Interface

All the gadgets in the Control window, and the mouse pointers can be edited.

The brushes are stored in the directory Brush/. All may be edited and using e.g. DPaint.

The following brushes are size 38x34:

add
del
link
none
one
rel
two
unlink

The following are 15x15:

1st
Last
Next
Prev

The following is 16x15:

Goto

The mouse pointers are stored in the directory Cursor/. All may be edited using the Workbench Pointer editor.

The following Pointers can be edited:

Xadd
Xdel
Xl1
Xl2
Xmov
Xone
Xrel
Xtwo
Xu1
Xu2

11 Internal file formats

The file format is subject to change at any time.

The current format for the main file is:

TSMorph 1.2
file_name_one
file_name_two
24_bit_file_name_1
24_bit_file_name_2
anim_file_name
w=a,h=b,Frames=c,Single=d,Start=e
x=n,y=m,x1=o,y1=p
.
.
.
p1=i,p2=j
.
.
.

where TSMorph 1.2 is a header record (not present in the previous version of TSMorph, old formats can still be loaded producing a warning message), a is the width, b the height, c the number of frames, d is 0 for Morph, 1 for Warp, 2 for Anim Morph and 3 for Anim Warp, e is the start frame number, n,m are coordinates on the first image, o,p on the second image, and i and j are the number of the points to join (starting from 0).

For animated Warps and Morphs the main file contains no points. Each frame has a set of points held in a file named with .nnn after the main file name, where nnn is the frame number. This file has a header of TSMorph 2.0 and then has the Points details.

12 ARexx interface to TSMorph-render and TSMorph

ARexx scripts are run before and after each image is rendered, and before each 24 bit image is loaded. The script names can be supplied as parameters (LOADSCRIPT, PRESCRIPT and POSTSCRIPT) to TSMorph-render.

An ARexx script can also be run by TSMorph to preview render an image. The script name is supplied in the PREVIEW parameter.

The suffix to each ARexx script should be .TSM.

ARexx script run before loading 24 bit image

This script is run before each 24 bit ILBM image is loaded.

It is passed the following parameters:

Frame       : The current frame number, starting at Start.
TotalFrames : The total number of frames being rendered.
Single      : Set to 1 if a Warp, 0 for a Morph, 2 for Anim Morph, 3 for Anim Warp.
Image       : Set to 0 for 1st image, 1 for second.
FileName    : Name of file just rendered.

This script can be used to change the format of the input file (by running it through a conversion program).

One example is included: @HTML <P> @HTMLOFF

@HTMLON
@{"Loadscript.TSM" ALINK "Rexx/Loadscript.TSM/Main"} - Do nothing example
@HTMLOFF

@HTMLON

ARexx script run before rendering

This script is run before each image is rendered.

It is also called for the first image (for warps and morphs) and for the last image (for morphs). By default the first and last frames are not rendered. Produce will need to be set to 1 to output these frames. This allows the first and last frames to be converted to the same format as the other output images.

It is passed one parameter - Base - the address of a structure which contains the following:

Frame       = 0  : The current frame number, starting at 1 (0 for 1st frame) - read only.
TotalFrames = 1  : The total number of frames being rendered - read only.
Single      = 2  : Set to 1 if a Warp, 0 = Morph, 2 = Anim Morph, 3 = Anim Warp - read only.
Movement    = 3  : 0 to 1024 - the proportion of movement from first to second image.
Red1        = 4  : 0 to 1024 - the proportion of Image 1 Red to use.
Green1      = 5  : As Red1 for Green.
Blue1       = 6  : As Red1 for Blue.
Red2        = 7  : 0 to 1024 - the proportion of Image 2 Red to use.
Green2      = 8  : As Red2 for Green.
Blue2       = 9  : As Red2 for Blue.
Produce     = 10 : Set to 0 to not render this frame, 1 otherwise.
RPlus       = 11 : 0 to 255 to add to Red in rendered image.
GPlus       = 12 : As RPlus for Green.
BPlus       = 13 : As RPlus for Blue.
RMinus      = 14 : 0 to 255 to subtract from Red in rendered image.
GMinus      = 15 : As RMinus for Green.
BMinus      = 16 : As RMinus for Blue.
DX          = 17 : 0 to ? - X amount to skip - See section parameters.
DY          = 18 : 0 to ? - Y amount to skip - See section parameters.
Start       = 19 : Starting frame number.

The values of these parameters may be set and read using the GetValue and StoreValue functions:

/* To read the value of e.g. Movement use:
   integer_variable = GetValue(Base,Movement)
*/

/* To set the value of e.g. Produce to 0 use:
   call StoreValue(Base,Produce,0)
*/

GetValue:Procedure
   Parse arg XBase, XAdd
   return C2D(IMPORT(D2C(STRIP(XBase) + (STRIP(Xadd) * 4)),4))

StoreValue:Procedure
   Parse arg XBase, XAdd, XVal
   call EXPORT(D2C(STRIP(XBase) + (STRIP(Xadd) * 4)),RIGHT(D2C(XVal),4,D2C(0)),4)
   return

The default values passed to the script for modification are:

Movement            : (1024 * Frame)/(TotalFrames + 1) Morphs
                      (1024 * Frame)/TotalFrames       Warps

Red1,Green1,Blue1   : Movement                         Morphs
                      1024                             Warps

Red2,Green2,Blue2   : (1024 - Movement)                Morphs
                      0                 Irrelevant for Warps

Produce             : 1                                Rendered frames
                      0                 Frames 0 and TotalFrames+1
RPlus,GPlus,BPlus   : 0
RMinus,GMinus,BMinus: 0
DX,DY               : Initially set by DX and DY parameters

Changing these values allows acceleration of movement, colour fades etc. and the generation of only some images (to check a long animation).

Example scripts included are: @HTML <P> @HTMLOFF

@HTMLON
@{"FadeToBlack.TSM" ALINK "Rexx/FadeToBlack.TSM/Main"} - Warp fade to black
@HTML <P>
@{"FadeToWhite.TSM" ALINK "Rexx/FadeToWhite.TSM/Main"} - Warp fade to white
@HTML <P>
@{"PixelMorph.TSM" ALINK "Rexx/PixelMorph.TSM/Main"}  - Morph by pixelating
@HTML <P>
@{"PixelWarp.TSM" ALINK "Rexx/PixelWarp.TSM/Main"}   - Warp pixelating
@HTML <P>
@{"PreAll.TSM" ALINK "Rexx/PreAll.TSM/Main"}      - Render all images
@HTML <P>
@{"Prescript.TSM" ALINK "Rexx/Prescript.TSM/Main"}   - Do nothing example
@HTMLOFF

@HTMLON

ARexx script run after rendering

This script is run after each image is rendered.

It is passed the following parameters:

Frame       : The current frame number, starting at Start.
TotalFrames : The total number of frames being rendered.
Single      : Set to 1 if a Warp, 0 for a Morph.
FileName    : Name of file just rendered.

This script can be used to change the format of the output file (by running it through a conversion program) or build an animation.

Three examples are included: @HTML <P> @HTMLOFF

@HTMLON
@{"PostAnim.TSM" ALINK "Rexx/PostAnim.TSM/Main"}   - Convert to Anim
@HTML <P>
@{"Postscript.TSM" ALINK "Rexx/Postscript.TSM/Main"} - Do nothing example
@HTML <P>
@{"ToHam.TSM" ALINK "Rexx/ToHam.TSM/Main"}      - Convert using PPM and Wasp
@HTMLOFF

@HTMLON

ARexx script to preview render

This script is run if the Preview... or Preview... menu item is selected. Its purpose is to preview render the image (it can actually do anything you like).

Before being called the current Settings are saved in T:TSMorph.prefs.

It is passed the following parameters:

Frame    : The frame number to render
FileName : The file name of the points file

Two examples are included: @HTML <P> @HTMLOFF

@HTMLON
@{"Preview.TSM" ALINK "Rexx/Preview.TSM/Main"} - Render and display 16 grey scale image
@HTML <P>
@{"PreAnim.TSM" ALINK "Rexx/PreAnim.TSM/Main"} - Render and display 16 grey scale Anim
@HTMLOFF

@HTMLON

13 Morphing algorithms

The morphing algorithm is defined using the parameters MODE and DEPTH to TSMorph-render.

The basic algorithm is to find 3 points which make a triangle around the point and morph this triangle between the start and end images.

The DEPTH parameter controls how many points will be checked to form a triangle. 0 means just the closest 3 points are examined, 1 the closest 4, 2 the closest 5 etc.

The MODE parameter controls both which triangle is chosen and what to do if no surrounding triangle is found.

If MODE=0 2 4 ... 30 (i.e. bit 1 not set [do not add 1]) then if no triangle surrounding the point is found examining the closest points then the 3 closest points are used to decide how to morph. Otherwise the point is assumed to be stationery.

If MODE=2 3 6 7 ... 30 31 (i.e. bit 2 set [add 2]) then all the closest points (the exact number controlled by DEPTH) are examined to determine the smallest triangle. Otherwise the first surrounding triangle found is used.

If MODE=4 5 6 7 12 ... (i.e. bit 3 set [add 4]) then a square algorithm is used to find the closest points. Otherwise all points are examined. Although using these MODEs could theoretically make the program run faster, it seems to generally run slower.

If MODE=8 9 10 ... (i.e. bit 4 set [add 8]) then a Delauany triangle algorithm is used to find triangles. For these modes the DEPTH parameter should normally be set to 0. Also floating point calculations are still done even if INTEGER is set to YES.

If MODE=16 17 ... (i.e. bit 8 set [add 16]) then the closest triangles are only calculated once at the start (based on the average of start and end). This should only be used if the points do not move a lot between the start and end images. It can speed things up a lot for a lot of frames. It does not make sense to use this for Animated Warps/Morphs. This uses a lot of memory:

    (DEPTH + 4) * Image_Width * Image_Height * 4

    e.g. 640x512 image, DEPTH=2 uses 7.5 MB (contiguous) memory

Therefore MODEs 0 and 1 should be faster than modes 2 or 3. The DEPTH parameter can also have a major effect on the rendering speed.

See Benchmarks.

Benchmarks

These benchmarks are based on a Morph provided by "Al Bet Sam That I’m Not Eloquent, Nancy Colours Eggs" <91016@tayloru.edu> of two 150x150 images with 41 control points.

Times are in seconds to generate the first frame on a 28MHz 68040 running in 32bit fast ram.

           ----------------------------------------------
           | 040 version  | 881 version  | 000 version  | Note all running on a 68040
           ----------------------------------------------
           |INT |   FPU   |INT |   FPU   |INT |   FPU   |   INTEGER=YES/NO/NO
---------------------------------------------------------
|MODE|DEPTH|    |    | AA |    |    | AA |    |    | AA | ANTIALIAS=NO/NO/YES
---------------------------------------------------------
|  0 |  0  | 6.2| 9.1|13.9|    |11.9|    |    |    |    | Shows the effect of DEPTH
|    |  5  |12.0|15.2|    |    |    |    |    |    |    |
---------------------------------------------------------
|  0 |  2  | 8.4|11.4|17.0| 8.8|14.1|18.5| 9.4|63.8|80.9| On a 68000 with 1MB chip ram, no
|  1 |     | 8.1|    |    | 8.5|    |    |   x|    |    | fast ram...
|  2 |     | 8.9|    |    |    |    |    |    |    |    |
|  4 |     |13.4|    |22.8|13.6|    |23.3|    |    |    | x = 262  (9.4 * 28)
|  8 |     | 7.6|    |    |    |    |    |    |    |    |
| 16 |     | 2.8|    |10.7|    |    |12.1|    |    |    |
| 17 |     | 2.5|    | 8.9| 2.6|    |10.3| 3.2|    |45.5|
---------------------------------------------------------
|  8 |  0  | 6.4|    |    |    |    |    |    |    |    |
---------------------------------------------------------
| 15 |  0  | 7.1|    |    |    |    |    |    |    |    |
---------------------------------------------------------
| 16 |  0  | 1.7| 4.6| 9.5| 1.7| 6.7|10.6| 2.5|56.0|    |
---------------------------------------------------------

14 File naming

File names can include the frame number.

The format of the frame number in the file name is specified using the following formats:

%ld     : Number left justified e.g.  '1','2',..,'10',..,'123',..
%3ld    : Number right justified e.g. '  1','  2',..,' 10',..,'123',..
%03ld   : Number right justified e.g. '001','002',..,'010',..,'123',..

Where the number can be changed e.g.

pic.%04ld   for Imagine 2.0 produced files
pic%03ld    for Vista produced files
name%ld     for files to run through mpeg

15 Error Messages

The following messages can be displayed in an Error Requester.

Error - Both Images must be the same size

This message should never be displayed. Images different sizes should be displayed instead.

Resolution - None required.

Unable to Open Grid Requester

TSMorph is unable to open the Add Grid requester. The normal reason would be lack of memory.

Resolution - Free up some memory and retry.

Error - Both X Cells and Y Cells must be > 0

This message is displayed if the Add Grid requester is used and either the X Cells or Y Cells is set to 0. The minimum allowed value is 1.

Resolution - Input at least 1 in both gadgets, or cancel the requester.

Error - Out of memory for points

This message is displayed after the Add Grid requester has been used and points and lines are being added to the images. Insufficient memory is available.

Resolution - Since it is possible that some of the points have been added to the images then you may wish to use the New Points menu item to delete all points. Then free up some memory and retry.

Error - No ILBM.BMHD chunk

The Image being loaded has no BMHD chunk.

Resolution - Specify the name of a correct ILBM image.

Error - Failed to allocate raster

There is insufficient memory to load the ILBM image.

Resolution - Free up some memory and retry.

Error - No ILBM.BODY chunk

The Image being loaded has no BODY chunk.

Resolution - Specify the name of a correct ILBM image.

Error - Not an ILBM

The Image being loaded is not and ILBM file.

Resolution - Specify the name of a correct ILBM image.

Error - Clipboard open failed

The program is unable to open the specified clipboard.

Resolution - Retry with the correct clipboard number, or use a different file name.

Error - xxxx; File open failed

File xxxx can not be successfully opened. The file does not exist (if trying to read), is already in use, or the filename is invalid.

Resolution - Retry with a valid file name.

Error - Parsing error; no top chunk

This is a technical error which should never occur.

Resolution - Unknown.

Error - Not enough memory

There is insufficient memory to save or load the IFF ILBM file.

Resolution - Free up some memory and retry.

Error - Failure opening TSMorph Window

The Information Window window could not be opened. There is probably insufficient memory.

Resolution - Free up some memory and retry.

Error - Failure setting up screen

The Information Window window could not be opened. Either the Public Screen is not open or there is insufficient memory.

Resolution - Free up some memory and retry, or correct the PUBSCREEN parameter.

Error - Can not Open xxxx.library(n)

The library xxxx version number n could not be opened. See Requirements for a list of libraries required. It could just be a lack of memory.

Resolution - Ensure you are running at least version 2.04 of the operating system, or free up some memory and retry.

Error - Unable to Allocate FileRequest

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Unable to Create Window Message Port

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Can not Open input.device

Insufficient memory is available.

Resolution - Free up some memory and retry.