
                      README 14. January 2008

                        AKs Gimp Xtensions 
                         Version 2.4/2.2

               Copyright (C) 2007-2008 by Andreas Krammel
               www.krammel.net    |    <info@krammel.net>



These programs are free software, you are allowed to redistribute them.

These programs are distributed in the hope that they will be useful,
but WITHOUT ANY WARRANTY, without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


=======================================================================
                            Overview
=======================================================================

<ak_gimp_xtensions_2.4.zip> is a collection of plug-ins and scripts to
bring vector orientated drawing to Gimp. This is done by adding style-attributes
to the paths in form of parasites (e.g. <ak-style-for-path-PATHTATTOO>).
Most of the numerical attributes, the path points itself, <@-date: > and <image: >
can be animated.

Tested with
  Gimp 2.4.2 (for Gimp 2.2.13 use <ak_gimp_xtensions_2.2.zip>)
  Windows XP.

The plug-ins exists for Windows only.

  1.) Pathgroups
  2.) Transform perspective tools
  3.) Edit Styles, draw paths, draw Text-Paths
  4.) Image-Paths and [Symbol] "text"
  5.) Keyspline-Paths [@], [@->S] ...
  6.) Scripts SIOD vs Tiny-Fu
  7.) Animation Rendering
  8.) 2.4 vs 2.2
  9.) Support and Donation



=======================================================================
  1.) Pathgroups
=======================================================================

Menu: <Image>/AK Path-Tools/Path-Groups .../Select

You can have multiple pathgroups with your image. A pathgroup is a set
of paths plus the belonging parasites (<PREFIX-for-path-PATHTATTOO>).
This helps to better organize a big amount of paths incl. their styles.
You can select, duplicate, add new, load and save pathgroups with a
GUI by choosing the option from the menu-path above.

COPY and PASTE function in these Path-Tools include the belonging parasites.

Because Gimps Undo-System does not include parasite changes, you should not undo a
pathgroup selection. Just bring up the selector GUI again and choose your previous pathgroup.
Undo will do single steps on single paths in this case.

If you load an external pathgroup then this is marked with the filename. Storing back
to the file means replacing the existing pathgroup within the file. If you save other pathgroups
they will be appended to the existing in that file.

=======================================================================
  2.) Transform perspective tools
=======================================================================

Menu: <Image>/AK Path-Tools/Transform Perspective/

This tool is using the active selected path as TO_PATH and the path below
as FROM_PATH. Both must have 4 points minimum (I prefer a Z-Shape),
where then a matrix is calculated to transform the first 4 points of
the FROM_PATH to the first 4 points of the TO_PATH. With this matrix
a transformation is done with your menu choice (<Active Drawable>,
<Locked Layers>, <Locked Paths | Layers> or <Locked Paths>) by using
the gimp_drawable_transform_perspective function for the drawables.
Have a look at examples\transform_perspective.xcf


=======================================================================
  3.) Edit Styles, draw paths, draw Text-Paths
=======================================================================

Menu: <Image>/AK Edit | Animate/Draw Path  (or Draw on ESL)

DRAW PATH:
--------------------
If you have no style attributes with your paths then the default <fill: 0 0 0>
is used and the paths or text-paths will be drawn in black.
To edit the style attributes, just bring up the Gui (Menu:/Edit Path-Style)
and select the desired attributes. E.g. if you select the fill attribute it
will use the back-ground color for it, now adjust the right color and try
<Draw Path> or <Draw on ESL> from your <Image>Menu or from the GUI/Edit.
If you draw on ESL (Edit Style Layer) it will add an new layer for that
path. If you select a different path the context will be updated
accordingly (fg-color, bg-color, gradient, pattern, brush).

<stroke: > uses always the fg-color and the selected brush. 
For <fill: > you can choose between bg-color, pattern and gradient.
If gradient is used then a control-path is added where you can adjust
the gradient start and stop.

If you add <rotate-at: > using GUI/Extra/Add Attribute/rotate-at
then a control-path is added where you can adjust the center and the
rotation (-180 ... +180 degree) which will apply to the draw path.
The attribute <rotate-at-add: > just sums up with <rotate-at: >, but
rotation greater then +-180 degree is accepted.

DRAW TEXT: (Have also a look at examples\text_paths.xcf)
--------------------
This is just be done by using " at the beginning and the end of the path-name.
These path-names will be drawn as text:
"First text"          --draw text-> First text
"Second text"#1       --draw text-> Second text
""Text" in text!"     --draw text-> "Text" in text!

For text-path only <fill: > is used not <stroke: > up to now. If you have not added
a <font-size: > attribute then the fontsize is calculated from the paths
abs(2nd_point_y - 1st_point_y). The second point is where the text's origin
is located. If you add an 3rd_point to the text-path then this angle for
rotating the text is used.
If you have not added a <font-name: > attribute then the current selected font is used.
Try also <xalign: >, <yalign: >, <text-offset: >, <baseshift: >, <letter-spacing: > etc..
You can align the text along a path using <text-path: >. Try also <palign: >,
0.0 means align text begin to path begin, 0.5 means align text-center to path-center
and 1.0 means align text-end to path-end.

There are several date format functions, all start with '%', so this character must be
escaped as well. The draw plug-in looks hereby after the dtf parasite, wich will be
setted by the <@-date: > attribute (animated better said recalculated as well), or you can
set it via script with
(plug-in-ak-dtf-set-date-from-string image "24. Dec 2007; 1. 2008" t). Have also a
look to the PDB for the other plug-in-ak-dtf-... functions.
If day=0 only Month and Year, if day=0 and month=0 only Year is drawn with %D
If t=0.0 on (plug-in-ak-dtf-set-date-from-string image "24. Dec 2007; 1. 2008" 0.0)
"%% Date: %D"     --draw text-> % Date: 24. Dec. 2007
"%% Date: %0D"    --draw text-> % Date: 24. 12. 2007
"%% Date: %1D"    --draw text-> % Date: 24. December 2007
"Date: %y/%m/%d"  --draw text-> Date: 2007/Dec./24
"Date: %y/%0m/%d" --draw text-> Date: 2007/12/24
"Date: %y/%1m/%d" --draw text-> Date: 2007/December/24

If t=1.0 on (plug-in-ak-dtf-set-date-from-string image "24. Dec 2007; 1. 2008" 1.0)
"%% Date: %D"     --draw text-> % Date: Jan. 2008
"%% Date: %0D"    --draw text-> % Date: 1. 2008
"%% Date: %1D"    --draw text-> % Date: January 2008
"Date: %y/%m/%d"  --draw text-> Date: 2008/Jan./0
"Date: %y/%0m/%d" --draw text-> Date: 2008/1/0
"Date: %y/%1m/%d" --draw text-> Date: 2008/January/0

On default english month names are used, to change this set new names with
(plug-in-ak-set-month-names "Januar; Februar; Mrz; ...") and
(plug-in-ak-set-month-names-short "Jan.; Feb.; Mrz; Apr.; ...")

DRAWGROUPS
--------------------
You can combine 2 or more paths to be draw together if you prepend {No.} to the pathname.
E.g.:
  {1} box 1
  {1} circle 1
  {1} "Text of Drawgroup {1}"
  {1} [Symbol]
If use <Draw on ESL> then all combined paths lock state goes true and the
ESL-Layer lock state goes true, so the transformation tools (scale, move, ...)
can act on them together.
A Keyspline-Path ([@]...) can NOT join a drawgroup, in this case ({1}[@]...)
it is not a Keyspline-Path anymore and it will be draw just as normal path.


QUICK REMOVE ATTRIBUTES
------------------------
If you press <Shift><Control> during the menu selection 'GUI Edit Style: /Extra/desired-attributte'
then this attribute will be removed, otherwise you can edit it.


=======================================================================
  4.) Image-Paths and [Symbol] "text"
=======================================================================

Menu: <Image>/AK Path-Tools/[@][@->S].../ Image-Path ...
----------------------------------------------------------
Before you adding an Image-Path make a selection where your image should be drawn,
or if no selection was made the image-size is used.

There are 3 different Image-Paths:

 \-Path means the image goes from upper-left to lower-rigth.
 i-Path means the image goes from center to lower-point.
 Z-Path means the image will be transformed to fit into the 4 corner points
 
You can also choose a specific layer or a timeline within the Image-Path, try
out the GUI options. If you use the image as marker with 'keep-aspect-ratio'
then the angle between 1st and 2nd point is used for the rotation (\- and i- only)
and the length is used to calculate the height. If you have selected a timeline
<@-timeline-t: > can be set for a certain time (0.0 ... 1.0), or if it is missing
the animation progress value is used.

Menu: <Image>/AK Path-Tools/[@][@->S].../ [Symbol] ...
----------------------------------------------------------
The Symbol-Path is a \-Path or an i-Path, the layer is equal
to the symbol-name, e.g <[Pyramid] path#1> means
the layer [Pyramid] is used within your <image: > file.
In addition you can add a text to be drawn with the symbol.
E.g. <[Pyramid] "Gizeh">, the first 2 points are for the image,
point 3 and 4 will be used for the text origin and font-size.
If you add an 5th point this will be use for the text rotation.


=======================================================================
  5.) Keyspline-Paths [@], [@->S] ...
=======================================================================

Menu: <Image>/AK Path-Tools/[@][@->S].../

[@]
--------------------------------
A Keyspline-Path is not drawn directly, it represents a time/progress curve.
Where the left-hand start-point represents the start (0.0) and the right-hand
end-point represents the end (1.0) of the time (passing from left to right).
The progress counts from bottom (0.0) to top (1.0) of the curve.

A Keyspline-Path must have a <@-tattoos: > attribute (except [@-Script]) which will
be set up on creation.
1. Lock the desired path for the animation (path from top to bottom will be tattoos from left to right)
2. Select the path for the naming
3. Lock a [@] keyspline if you wish to copy that curve
4. Create the keyspline by using the Menu: <Image>/AK Path-Tools/[@][@->S].../[@] / locked Paths

This will create a Keyslpine-Path <[@] selected pathname>, the attribute may look like this
<@-tattoos: 17 1264 26> on an animation with 3 paths. Left to right means top to bottom, that means
progress 1.0 is draw path with tattoo 17, progress 0.0 draw path with tattoo 26.
If progress is in between 0.0 and 1.0 then the path and the attributes are calculated in between,
a temporary path is created and drawn. The default time (Default t) for the Keyspline-Path is 0.5
which is used for 'Draw Path' or 'Draw on ESL', you can change this in the Edit Style GUI.
Keep in mind that you can adjust the Keyspline-Path in any shape so you can animate from 17 ... 26
or vice versa. If you adjust the Keyspline-Path non linear then this will show up in a non linear
animation, take a look at the bouncing ball animation in the example.

You can combine also 2 or more <@-tattoos: > using the semicolon, e.g. <@-tattoos: 17 1264 26; 34 18>
This means animation <@-tattoos: 34 18> is drawn before <@-tattoos: 17 1264 26> with the same progress.

You can use Keyspline-Path with only 1 path to animate as well, but then what to animate must be in the
Keyspline-Path attributes. E.g. <fill: 255 0 0; 0 0 255> as attribute from the Keyspline-Path means
animate the fill color with progress-value 1.0=red (255 0 0) and progress-value 0.0=blue (0 0 255).
The default color animation is 'HSV short', means from red to blue (or vice versa)
in the short HSV way just passing a magenta tone.
'HSV long' would mean go over yellow, green and light blue. Try also RGB, etc...

[@] MOTION-PATH (Have also a look at examples\motion_path.xcf)
-----------------
If you add <@-motion-path: > within the 'GUI Edit-Sytle:Extra/Add Attributes/@-motion-path/' then
your drawn paths moves along this path. There are 3 different types of <@-motion-angle: >

  fixed 30      ---> used fixed angle of 30 degress
  auto 40       ---> calculate angle of motion-path plus 40 degress
  roll 130      ---> calculate angle along the path-length, rotate 360 degress every 130 pixel


[@->S] [@<-S] STROKE ANIMATION
--------------------------------
As described above
1. Lock the desired path for the animation (path from top to bottom will be tattoos from left to right)
2. Select the path for the naming
3. Lock a [@] keyspline if you wish to copy that curve
4. Create the keyspline by using the Menu: <Image>/AK Path-Tools/[@][@->S].../[@->S] locked Paths

The difference hereby is that the path strokes will be animated, progress 0.0 means draw paths
at length 0 (actually nothing), progress 0.5 means draw paths at half of complete path length
and progress 1.0 means draw complete paths. With [@<-S] the drawing begins from the end.
Not only 1 path stroke can be animated, you can combine more paths then every path length is calculated
separately (if the the pathname starts with a number e.g. <340.2 borderpath#5> this will be added) and the
largest length will be for progress 1.0. So you can start the single path strokes right on time.
To create multiple path stroke animations use 'Menu: <Image>/AK Path-Tools/Join to Reference'.


[@->Script]
--------------------------------
This Keyspline-Path does not need a <@-tattoos: >, you just select the external batch file and after creation
you can adjust the curve. Within in the batch file you can use the variables:
image   ---> current image
draw    ---> current drawable
av      ---> progress number 0.0 ... 1.0, or the attribute value of <@-script-av: > if exists
name    ---> the name of the Keyspline-Path

Another attribute <script-eval: > exists which can be used for any path, it holds the script evaluated
before any other drawing.

<@-script-set-bbox: > allows you to set the bounding box parasite from a specific path before evaluating
the script, so you can retrieve the dimension with (plug-in-ak-bbox-image) and (plug-in-ak-bbox-path) for
further processing. The bbox-path parasite is set every time a path is drawn (min max value of the stroke),
the  bbox-image parasite is set every time an image is drawn (min max value of drawn the image).


[@] t_(timeline)
--------------------------------
[@], [@->S], [@<-S] and [@->Script] can have set the attribute <@-timeline: >. This represents a
local timeline of the image which is renderer before the animation drawings (or [@-Script]).


=======================================================================
  6.) Scripts SIOD vs Tiny-Fu
=======================================================================

There are different ways to use scripts with the animations. One described above is
using the Keyspline-Path [@-Script] ..., hereby the <@-script: > attribute points to
an external script file. For all path <script-eval: > can be used for short scripts to
be evaluated before the other actions to the path are done. A 3rd possiblity is within
the Timeline-Editor where you can add a script to every timeline entry, which will be evaluated
after all drawings. 3 global scripts for all timeline entries can be set for
execution 'Before-Rendering', 'After-Rendering' and 'Before-Save'. In additon a specific
script 'Before-Save' only for the desired timeline can be choosen. All these scripts are
using (script-fu-ak-eval4 ...) or in Tiny-Fu as fall-back (plug-in-script-fu-eval ...) on 
recursive calls of a script out of a plug-in. This is done because Tiny-Fu causes problems
with recursive calls, on the other hand to run (plug-in-script-fu-eval ...) takes a lot of
time to start up that procedure which slows down the rendering process dramatically if often used.
So I still prefer using SIOD even with Gimp 2.4.2, but both work with my programs.
To use SIOD you need to install your old *.scm scripts to the 'scripts' directory
and the old (e.g Gimp 2.2.13) script-fu.exe to your 'plug-ins' directory,



=======================================================================
  7.) Animation Rendering
=======================================================================

Menu: <Image>/AK Edit | Animate/Animation GUI

The Animation GUI allows preview rendering of Keyspline-Paths and Image-Paths with timeline.
If you want to store animations as single frames to disk you need to create a timeline.
After using 'GUI Preview: Timeline/New' you need to insert an keyspline or a path or a script
via 'GUI Timeline: Edit/Insert Animation', if you are selecting a pathgroup here then all Keyspline-Path
in that group are animated for that timeline entry. Adjust the begining, duration, fade_in, etc.
to your desires, select the layer you wish to be drawn on and your first timeline is ready.
This will be saved with the image (like the pathgroups, style attributes etc...). To render
the timeline you can choose from 'GUI Timeline: Edit/Render'.
Also 'Menu: <Image>/AK Edit | Animate/Render Timeline' is possible.

Another way to render timelines (only with AKs Gimp Xtensions  2.4)
is with the external program 'ak_render_xcf.exe' wich needs to be installed in the Gimps 'bin' directory.
The main reason for this external program is because Gimp has some memmory leaks and even closing all
images and plug-ins does not free all memmory. So rendering a lot of frames might slow down the system,
in 'ak_render_xcf.exe' you can select a block size which will be rendered then gimp_quit is executed
and the render process will be restarted again. This needs gimp-console-2.4.exe otherwise a command screen
is asking to "Press a key"!

The GUI is mostly self explaining so starting with the attached examples\gimp_me.xcf makes you hopefully
a bit familiary with the animation process.


=======================================================================
  8.) 2.4 vs 2.2
=======================================================================

The main difference between this two versions is that AKs Gimp Xtensions 2.2 is NOT drawing 
paths with more then 1 non_closed stroke inside. This is because the Gimp 2.2 API
has a bug in gimp_path_get_points and gimp_path_set_points.
Gimp 2.4 introduces gimp_vectors... which solve that problem and is used in AKs Gimp Xtensions 2.4!


=======================================================================
  9.) Support and Donation
=======================================================================

If you feel the plug-in collection is useful and you want to support my work,
then your donation is very welcome. Please send your Euro- or Dollar-Bills
to my address below

  Andreas Krammel
  Neue Heimat 21
  D-82377 Penzberg
  Germany
  

Best regards and have fun

Andreas Krammel
www.krammel.net

