MPMorph 4.8 Contents
********************

@Remark $VER: MPMorph_guide 4.8 (18.3.97)

For updates etc. see <http://www.topic.demon.co.uk>

Note MPRender can now be compiled on non Amiga computers:

See @{"Readme.unix" link "Readme.unix/main"}.

Quick overview
**************

For a quick tutorial see @{"Tutorial.guide" link "Tutorial.guide/Main"}.

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

     MPMorph   Edit the Morph parameters
     MPRender  Generate the morphed images

See @{"MPRender.guide" link "MPRender.guide/main"} for information on the render program.

Installation instructions
*************************

If you wish to use Installer then MPMorph can be installed using the supplied script. If not then you are on your own!

Software and Hardware required
******************************

OS3.0+ is required to run MPMorph.

The following are used if present:

     reqtools.library         38 reqtools is ©1991/1992 Nico François
                                 This is required for Animated Warps/Morphs
     egs.library              0  EGS is © Copyright 1990/93 VIONA Development.
     egsintui.library         0
     egsgfx.library           0
     egsrequest.library       0

Tool types and Shell parameters
*******************************

Both MPMorph and MPRender can be run from the Shell or the Workbench. Most parameters can be edited using the Settings menu.

Parameters can be supplied, normally either on the Shell command line, as Icon Tool Types on the Project, MPMorph or MPRender 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) MPMorph.prefs
        in the project directory for the workbench,
        the current directory from the Shell.
     4) MPMorph.prefs
        in the directory MPMorph was loaded from.
     5) ENV:MPMorph/MPMorph.prefs

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

The following parameters can be supplied:

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:MPMorph/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:MPMorph/def_prefs if this exists, secondly from ENV:SYS/def_prefs, otherwise the default project Icon is used.

PUBSCREEN=pubscreenname
=======================

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

This parameter is not changed by Requester loaded projects.

It can be changed using the menu item, a requester is displayed allowing the input of the screen name, but any change is ignored until MPMorph is reloaded.

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

PORTNAME=name
=============

This gives the name of the ARexx port to open.

The default is MPMORPH.

See @{"MPMorph-rexx" link "MPMorph-rexx/main"}.

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, a requester is displayed allowing the input of the screen mode, but any change is ignored until MPMorph is reloaded.

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

CUSTOMDEPTH=4
=============

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

It can be changed using the menu item, a requester is displayed allowing the input of the screen mode, but any change is ignored until MPMorph is reloaded.

The default value is 4.

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.

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.

REQTOOLS=YES/NO
===============

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.

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.

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.

When set to YES help is continuously displayed using amigaguide.

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:MPMorph/MPMorph.prefs when MPMorph is quit. This parameter and menu item enable this behaviour to be turned off.

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 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.

PREVIEW=scriptname
==================

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

The default script is:

@{"Rexx/Preview.MPM" link "Rexx/Preview.MPM/main"}.

See @{"Preview.guide" link "Preview.guide/main"}.

The version supplied displays a GUI to render the image as a 16 colour grey scale.

It can be changed using the menu item, a requester is displayed allowing the input of the value.

F1 is a short cut to this script.

USER2=scriptname
================

This specifies the name of an ARexx script to run when F2 is pressed.

The default script is:

@{"Rexx/EdgePoints.MPM" link "Rexx/EdgePoints.MPM/main"}.

See @{"EdgePoints.guide" link "EdgePoints.guide/main"}.

This displays a requester to Edge Detect the images.

USER3=scriptname
================

This specifies the name of an ARexx script to run when F3 is pressed.

The default script is:

@{"Rexx/IndexHelp.MPM" link "Rexx/IndexHelp.MPM/main"}.

See @{"RunMPIndex.guide" link "RunMPIndex.guide/main"}.

This displays the index of all the help files.

USER4=scriptname
================

This specifies the name of an ARexx script to run when F4 is pressed.

The default script is:

@{"Rexx/RTPreview.MPM" link "Rexx/RTPreview.MPM/main"}.

This continuously displays a preview, updating the display when any editing is done.

Rerun this script to stop the preview rendering.

For fastest previewing set the 24 bit images to grayscale PBM versions of the rendering size of the images and set the number of frames to 1.

USER5=scriptname
================

This specifies the name of an ARexx script to run when F5 is pressed.

There is no default script.

USER6=scriptname
================

This specifies the name of an ARexx script to run when F6 is pressed.

There is no default script.

USER7=scriptname
================

This specifies the name of an ARexx script to run when F7 is pressed.

There is no default script.

USER8=scriptname
================

This specifies the name of an ARexx script to run when F8 is pressed.

There is no default script.

USER9=scriptname
================

This specifies the name of an ARexx script to run when F9 is pressed.

There is no default script.

RECENT1=filename
================

This is the most recent file opened.

RECENT2=filename
================

This is the second most recent file opened.

RECENT3=filename
================

This is the third most recent file opened.

RECENT4=filename
================

This is the fourth most recent file opened.

RECENT5=filename
================

This is the fifth most recent file opened.

The Information Window
**********************

This window is always displayed when MPMorph is running. It displays information about the current project. The window title is MPMorph, 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 MPRender.

Gadgets in Info Window
======================

@font topaz.font 8

The Information Window appears with gadgets:

     ----------------------------
     |.|MPMorph|I-gad-Zoom|I-gad-Depth|
     |--------------------------|
     |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 ...|
     |Set Size... Scale...|
     | Single @{u}F@{uu}rames.. St@{u}a@{uu}rt ..|
     |     @{u}N@{uu}ame ............  X|
     |Edit Points...|
     ----------------------------

Help Text gadget
----------------

This gadget displays short help messages.

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. It is displayed in the first Edit Window when editing points.

o can be used to activate this gadget - see 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 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 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 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. Note: MPMorph 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 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 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. Note: MPMorph 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 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 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.

Set Size gadget
---------------

This displays a requester, see SetSize, to set the size of the rendered image. Points are not scaled.

z is the same as using this gadget - see Keyboard.

Scale gadget
------------

This displays a requester, see Scale, to scalet the size of the rendered image. Points are scaled.

s is the same as using this gadget - see Keyboard.

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 Keyboard.

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 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 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 MPRender.

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 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 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 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.

Drag gadget
-----------

This allows the window to be moved.

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/Recent sub menu
...................................

This list the 5 most recent open files, allowing them to be opened without a file requester.

Info Window Project/Recent 1 menu item
======================================

This opens the most recently opened file.

Info Window Project/Recent 2 menu item
======================================

This opens the second most recently opened file.

Info Window Project/Recent 3 menu item
======================================

This opens the third most recently opened file.

Info Window Project/Recent 4 menu item
======================================

This opens the fourth most recently opened file.

Info Window Project/Recent 5 menu item
======================================

This opens the fifth most recently opened file.

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 File Format.

Info Window Project/Save As... menu item
........................................

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

See 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 File Format.

Info Window Project/About... menu item
......................................

This displays some program version information in the About Requester.

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.

Info Window Project/Quit menu item
..................................

This quits MPMorph.

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

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.

Setting/Load Settings... menu item
..................................

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

The default name is MPMorph.prefs.

Settings/Save Settings menu item
................................

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

If CREATEICONSP is set then an Icon is saved as well

Unless KEEPSETTINGS is set to NO current settings are saved in ENV:MPMorph/MPMorph.prefs whenever MPMorph 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 MPMorph.prefs.

Setting/Reset To Defaults menu item
...................................

This resets settings to there default values.

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

Settings/Last Saved menu item
.............................

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

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

Setting/Restore menu item
.........................

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

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

User menu
---------

This contains ARexx scripts to run.

Preview menu item
.................

This runs the script provided by the PREVIEW parameter.

User2 menu item
...............

This runs the script provided by the USER2 parameter.

User3 menu item
...............

This runs the script provided by the USER3 parameter.

User4 menu item
...............

This runs the script provided by the USER4 parameter.

User5 menu item
...............

This runs the script provided by the USER5 parameter.

User6 menu item
...............

This runs the script provided by the USER6 parameter.

User7 menu item
...............

This runs the script provided by the USER7 parameter.

User8 menu item
...............

This runs the script provided by the USER8 parameter.

User9 menu item
...............

This runs the script provided by the USER9 parameter.

Start Learning... menu item
...........................

This displays a file requester to select a file to which to start recording actions as an ARexx script. .MPM should be used as a file extension.

Stop Learning menu item
.......................

This stops recording user actions.

Macro menu item
...............

This displays a file requester allowing an ARexx macro to be played. .MPM is used as a file extension.

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 Get File One.

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

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

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

     zZ Same as Set Size gadget.

     sS Same as Scale gadget.

     rR Cycle Single image gadget.

     f  Activate Frames gadget.

     a  Activate Start gadget.

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

     p  Same as Edit Points gadget

Help displays context sensitive help using amigaguide.

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 MPMorph for non-animated Warps/Morphs and MPMorph - Frame nnn for animated Warps/Morphs.

Control and Image Window gadgets
================================

@font topaz.font 8

The Control Window appears with gadgets:

     --------------
     |.|Mov|Con-gad-Depth|
     |------------|
     |ONE TWO|
     |REL ADD|
     |DEL LNK|
     |UNL MOV|
     ||<<-?->>||
     --------------

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 Drag gadget
--------------------------

This is a standard drag gadget.

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 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 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 MPMorph.

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. 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:

Keyboard controls in the Control Window
=======================================

Help displays context sensitive help using amigaguide if available.

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:

     ------------------
     |.|filename|E-gad-ZoomE-gad-Depth|
     |----------------|
     |             |  |
     |             ||||
     |             ||||
     |             ||||
     |             ||||
     |             |/||
     |             |\||
     |----------------|
     |-------<-->|//|
     ------------------

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 Drag gadget
------------------------

This moves the window.

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.

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.

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

     ---------------
     |.|Add Grid|Req-Add_Grid-gad-Depth|
     |-------------|
     | @{u}X@{uu} Cells ...|
     | @{u}Y@{uu} Cells ...|
     |             |
     | OK Cancel|
     ---------------

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.

Set Render Size
===============

This sets the size of the render. It displays two gadgets.

Set Render Size X gadget
------------------------

This sets the width of the render.

Set Render Size Y gadget
------------------------

This sets the height of the render.

Scale Render Size
=================

This scales the size of the render. It displays two gadgets.

Scale Render Size X gadget
--------------------------

This sets the width of the render.

Scale Render Size Y gadget
--------------------------

This sets the height of the render.

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.

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.

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

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 MPMorph, 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.

ARexx interface to MPMorph
**************************

MPMorph has a full ARexx interface.

See @{"MPMorph-rexx" link "MPMorph-rexx/main"}.

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

Error Messages
**************

The following messages can be displayed in an Error Requester.

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 - Failure opening MPMorph 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.

Error - Unable to Allocate Zoom raster
======================================

Insufficient memory is available.

Resolution - Free up some memory and retry. If you still do not have enough memory then rerun specifying ZOOM=OFF as a parameter.

Error - Unable to SetMenuStrip
==============================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Unable to OpenWindowTags
================================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Unable to AllocMem for Filename
=======================================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Unable to Allocate xxxx Gadget
======================================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Unable to Allocate xxxx Image
=====================================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Failure loading Image 'xxxx'
====================================

There was an error loading the image xxxx. Another error message should previously have been displayed.

Resolution - See previous error message.

Error - Unable to GetScreenDrawInfo
===================================

Insufficient memory is available.

Resolution - Free up some memory and retry.

Error - Unable to LockPubScreen(xxxx)
=====================================

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 - Invalid file format - Line 'xxxx'
=========================================

The points file being loaded is in an incorrect Format or is not a points file.

Resolution - Specify a correct points file or manually edit the file and retry.

Error - Out of memory for points
================================

Insufficient memory is available.

Resolution - Free up some memory and retry after selecting either New or New Points to delete existing points.

Error - Invalid point link - Line 'xxxx'
========================================

The points linking specified in the input file is invalid.

Resolution - Manually edit the input file - See Format and retry.

Error - Error closing file 'xxxx'
=================================

The file xxxx could not be successfully closed. The disc may be full.

Resolution - If saving then save the file to a different disk or free up some disk space and retry with another name. The original file may not be accessible until after a reboot.

Error - Error opening file 'xxxx'
=================================

The file xxxx could not be opened. The file does not exist (when reading), the name is invalid, the file is already in use, or the disk is write protected.

Resolution - Use a different file name or allow the disk to be written to.

Error - Error writing to 'xxxx'
===============================

The file xxxx could not be successfully written to. The disc may be full. The file has not been successfully saved.

Resolution - Save the file to a different disk or free up some disk space and retry.

Error - Point already linked to 16 points
=========================================

Any point can only be linked to up to 16 other points. Note: the links are only for clarity and do not effect the rendering process.

Resolution - Unlink the current point from some other point and retry.

Error - Error no memory for new point
=====================================

There is no memory to add the new point.

Resolution - Free up some memory and retry.

Error - Assuming version 1.0 file format
========================================

The current version of the File Format has a header record. This error is saying no header is present, it is assumed that the file is in an old format.

Resolution - Select OK to continue. Load and Save in MPMorph to save in the new format if required.

Error - Must have at least one frame
====================================

This is displayed when trying to edit points on an Animated Morph/Warp when the number of frames is 0.

Resolution - Set the number of frames to at least 1.

Error - Error Saving Settings 'xxxx'
====================================

This message is displayed when MPMorph has been unable to save settings in the named file. If KEEPSETTINGS is set to YES then settings are saved in ENV:MPMorph/MPMorph.prefs when the program is quit.

Resolution - Supply a correct filename, set KEEPSETTINGS to NO, or create the directory ENV:MPMorph

Error - Error Loading Settings 'xxxx'
=====================================

MPMorph has had a problem loading the specified file. The file probably does not exist.

Resolution - Specify a correct file name

Error - Error opening screen
============================

MPMorph has been unable to open the requested screen. This could be because the CUSTOMDEPTH is too great for the CUSTOMMODE, there is not enough memory, or some other related reason.

Resolution - Check you have enough memory, make sure the screen depth is OK for the screen mode.

Error - Unable to get DrawInfo
==============================

MPMorph has been unable to obtain some information from the Workbench, probably due to lack of memory.

Resolution - Free up some memory and retry.

Error - Unable to lock Workbench
================================

MPMorph has been unable to obtain some information from the Workbench, probably due to lack of memory.

Resolution - Free up some memory and retry.

Invalid screen mode xxxx
========================

The screen mode specified by CUSTOMMODE is not a valid screen mode.

Resolution - Check the screen mode against the list show in the preferences screen mode requester.

MPMorph is attempting to close this ...
=======================================

MPMorph is trying to close the Public Screen that it opened but is unable to as there are locks (probably open windows) on the screen.

Resolution - Close all other open windows on the screen and retry.

Failure loading image xxxx
==========================

MPImage.library has failed to load an image.

Resolution - the message should give more information.

Failure Resizing Image xxxx
===========================

MPImage.library has failed to resize an image.

Resolution - the message should give more information.

Failure displaying requester xxxx
=================================

MPGui.library has failed to display a requester.

Resolution - the message should give more information.

Error - Creating Port
=====================

There has been a problem creating the ARexx Port.

Resolution - Is ARexx running? Out of memory? Check PORTNAME parameter.

Error - Generating Triangles
============================

There has been a problem generating triangles.

Resolution - Out of memory?

Known (and unknown errors)
**************************

  * Known Problems

       * The docs are sparse in places and are probably incorrect as well!

       * Unsaved project does not check that gadgets really have been edited.

       * This guide sometimes has very long lines. Also bold items following * are followed by too many spaces. This appears to be due to a problem with MakeInfo, menus and lists.

       * This guide may not look correct when using amigaguide.library versions before 40. This will not be fixed.

       * Sizing EGS windows from the top or left may corrupt the display. I believe this an EGS problem.

       * MPRender is not yet localized.

       * When moving or sizing an image window sometimes lines can be drawn twice, clearing the lines. Closing and reopening will redraw correctly.

       * It takes a long time to open a Public Screen - ObtainPen??

  * Unknown Problems?

       * None at present.

Please report any other bugs by EMail to mark@topic.demon.co.uk or mpaddock@cix.compulink.co.uk.

List of things To Do
********************

  * 001 - Add a real realtime preview. Doable but a lot of work.

  * 002 - Run scripts on Start, Open, EditPoints etc. allowing e.g. Timed backup. Easy.

  * 003 - Fix bugs!

  * 004 - Handle Cybergraphics correctly. Needs my currently conceptual ECSCybergraphics.library.

  * 005 - Easier Anim Warps/Morphs - interpolation of points so all frames do not have to be designed.

  * 006 - Include a program to generate Anims - possibly add support to MPImage.library.

  * 007 - Improve localisation of MPGui.library to open language based Guis.

  * 008 - Localise scripts.

  * 009 - Add language catalogs for everything.

  * 010 - Improve .html doc translation to handle rx links.

Please send any other suggestions or vote for me to do any of the above by EMail to mark@topic.demon.co.uk or mpaddock@cix.compulink.co.uk.

Hardware and Software used in development
*****************************************

  * HSPascal            Editor.

  * SAS C               Code.

  * GadToolsBox         Info, and Progress Windows. GadToolsBox is © Copyright 1991,92 Jaba Development.

  * DPaint              Control Window gadgets/Pointers.

  * Workbench 2.04      GUI.

  * MakeInfo            Documentation.

  * Iff2Src             Control Window gadgets. Iff2Src is © J Tyberghein.

  * ILBMtoC             Pointers.

  * IconEdit            Pointers.

  * NewIff              Various IFF routines.

  * ReqTools            For nicer requesters. ReqTools is © 1991/1992 Nico François

  * IJG JPEG software   For the PPM, TARGA, GIF and JPEG file loading code.

  * EGS                 For the EGS interface.

  * AG2TXT              For the .doc file. AG2TXT is Copyright (c) 1993 Jason R. Hulance.

  * Fenster             To capture the windows

  * MKANIM              To generate Animations. MKANIM is Copyright © 1993 by John Bickers.

  * Commodore Amiga 2000 with 1MB chip ram,

  * Commodore 1960 monitor,

  * GVP SCSI hard card with 52MB Quantum disc,

  * RCS Fusion Forty accelerator with 8MB fast ram.

Version History (since TSMorph 3.3)
***********************************

  * Version 4.8

       * MPRender now uses COLOURS parameter.

       * Added full .html docs.

       * Spelling mistakes and version fixed in MPImage.library.

       * Reordered MPMorph catalog for easier localisation.

       * Updated bugs.

       * Added TODO list.

       * Noted WWW support page.

  * Version 4.7

       * Fixed enforcer hit in MPRender.

       * Updated algorithms to indicate memory usage.

       * Corrected version in Install script.

       * Updated install script for cjpeg/djpeg to match standard usage.

  * Version 4.6

       * New version of MPGui.library which should work if opened more than once.

       * New version of MPImage.library.??? which fixes SaveMPImage() bug.

  * Version 4.5

       * Fixed IndexHelp.MPM to work correctly

       * New versions of libraries and tools which open locale.library(38) to work on OS3.0.

       * New version of MPImage.library.??? which fixes enforcer hit.

  * Version 4.4

       * Bug fixes.

       * Added CTRL-C checking to MPMorph and MPRender.

       * Added RTPreview script (USER4).

       * Added LastUpdate to Rexx GetAttr.

       * Added Saved to Rexx SetAttr.

       * Added COPY/S to Rexx SaveAs

       * Renumbed some catalog message - some work still to be done.

       * Updated some scripts.

       * Added NOPROGRESS to MPRENDER.

       * Added PROGRESSHOOK to MPRENDER.

  * Version 4.3

       * Loads of changes. Following is only partial.

       * Renamed MPMorph/MPRender

       * Faster rendering.

       * Removed render settings from MPMorph.

       * Reordered some MPMorph menus.

       * Guis by MPGui.library.

       * Image loading/saving by MPImage.library.

       * Sysihack compatible.

       * OS3.0+ only.

       * Scaled menu checks and Amiga keys.

       * Open recent files.

       * Two preferences editors/settings files.

       * Full ARexx interface.

       * Scales input images.

Hints & Tips
************

This section supplies some hopefully useful information which may not be immediately apparent elsewhere.

Speed?

If you do not have an FPU then set the INTEGER parameter to YES. Even if you do have an FPU this may still make things run faster.

If it still slow then try changing DX and DY to 1 (or more).

If you have lots of memory then setting the precalculate part of MODE should help.

What MODE?

This depends on the type of Morph.

If you are, say, rotating some text on a background, then it is probably best to set the stationary part. You would NOT want to set the precalculate once part.

If you are morphing, say, two faces where the points do not move much between the first and last image then it may be best to set the precalculate part (provided you have enough free memory). Setting the Delaunay part may also be a good idea.

Setting search is probably not a good idea.

Not enough memory for MPMorph

If you run out of Chip memory when trying to load large images then try setting ZOOM to OFF.

Copyright and distribution requirements
***************************************

      MPMorph - Amiga Morphing program
      Copyright (C) © 1996 Mark John Paddock

      This program is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published by
      the Free Software Foundation; either version 2 of the License, or
      any later version.

      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      GNU General Public License for more details.

      You should have received a copy of the GNU General Public License
      along with this program; if not, write to the Free Software
      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

      mark@topic.demon.co.uk
      mpaddock@cix.compulink.co.uk

MPMorph IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO WARRANTIES ARE MADE.  ALL USE IS AT YOUR OWN RISK.  NO LIABILITY OR RESPONSIBILITY IS ASSUMED.

MPMorph is ©1995 Mark John Paddock

Please send any criticisms, bugs, etc. by EMail to mark@topic.demon.co.uk or mpaddock@cix.compulink.co.uk.

         The Delaunay code was written by Dave Watson and uses the algorithm described in -
         Watson, D.F., 1981, Computing the n-dimensional Delaunay tessellation with
         application to Voronoi polytopes: The Computer J., 24(2), p. 167-172.