[gimp-web-devel/pat/bootstrap] Issue #5: porting tool specifications from old wiki.

[Jehan <jehanp src gnome org>]

commit eb6c5b59c13b4758c779fa91bdec25a680ccc4e9
Author: Jehan <jehan girinstud io>
Date:   Sun Sep 11 21:48:31 2022 +0200

    Issue #5: porting tool specifications from old wiki.
    
    Ported to markdown and added to specifications/ subdirectory:
    
    * wiki/Hacking:WarpTool%2FUI_design_info-20210514160613-edit.txt
    * wiki/Mindstorm:n-point_image_deformation_tool-20151015040112-show.txt

 .../Depth_of_control_point.png                     | Bin 0 -> 119140 bytes
 .../Source_and_destination_pose.png                | Bin 0 -> 143594 bytes
 .../n-point_image_deformation_tool/_index.md       | 125 +++++++++++++++++++++
 content/core/specifications/warp-tool.md           |  78 +++++++++++++
 4 files changed, 203 insertions(+)
---
diff --git a/content/core/specifications/n-point_image_deformation_tool/Depth_of_control_point.png 
b/content/core/specifications/n-point_image_deformation_tool/Depth_of_control_point.png
new file mode 100644
index 0000000..12fae74
Binary files /dev/null and 
b/content/core/specifications/n-point_image_deformation_tool/Depth_of_control_point.png differ
diff --git a/content/core/specifications/n-point_image_deformation_tool/Source_and_destination_pose.png 
b/content/core/specifications/n-point_image_deformation_tool/Source_and_destination_pose.png
new file mode 100644
index 0000000..e2d5637
Binary files /dev/null and 
b/content/core/specifications/n-point_image_deformation_tool/Source_and_destination_pose.png differ
diff --git a/content/core/specifications/n-point_image_deformation_tool/_index.md 
b/content/core/specifications/n-point_image_deformation_tool/_index.md
new file mode 100644
index 0000000..ab7409a
--- /dev/null
+++ b/content/core/specifications/n-point_image_deformation_tool/_index.md
@@ -0,0 +1,125 @@
+---
+title: "Mindstorm: n-point deformation tool"
+Author: "GIMP team"
+Date: 2015-10-15
+---
+
+**NOTE: this is a "mindstorm" document salvaged from our old wiki for a
+tool which is still in the "Playground" section of GIMP. It should
+eventually be transformed into a proper specification with final UX
+choices.**
+
+## Introduction
+
+This is a description of planned features of n-point deformation tool. It should lead to UI specification.
+
+At the beginning, an image is opened and user selects n-point deformation tool. When he clicks on the image, 
mesh is automatically created above it. User can add points onto image and manipulate with them. He can also 
manipulate with mesh and control the deformation process – more below.
+
+
+### Mesh remarks
+
+Mesh above the image is created automatically with use of alpha channel. When there isn't any alpha channel, 
mesh is created above the whole image.
+
+The deformation method uses two meshes. One is called 'source pose' mesh, the other is called 'destination 
pose' mesh. Source pose mesh is always hidden and destination pose mesh can be visible. Only destination pose 
mesh is deformed.
+
+Mesh (lattice) for this method usually consists of squares. The deformation method is not limited to square 
mesh but square mesh can be constructed in an easier way, usually with less elements (than triangle mesh), 
and with small tweaks we can achieve similar precision as with triangular mesh.
+
+For this method it holds that with decreasing lattice square size (i.e. increasing number of mesh elements), 
precision of result is increasing, but inefficiency of the algorithm is increasing as well. User should have 
an option to adjust the balance.
+
+![File:Source_and_destination_pose.png](Source_and_destination_pose.png)
+
+## Control points manipulation
+
+### Add control points
+
+With a click at some position on image, control point is added. User can add control points at arbitrary 
positions on image (except position [some radius around it which depends on mesh square size](or) where a 
point is already placed) – mesh will be adjusted according to that.
+
+
+### Selection, deselection, multi-selection
+
+More or less the same as sections with same names in [Cage tool 
specification](http://gui.gimp.org/index.php/Cage_tool).
+
+
+### Delete control points
+
+Selected control points are deleted by `<delete>` key. Last added point can be deleted by `<backspace>` key.
+
+### Deformation of the image
+
+When user moves (click – drag – release) a control point (or multi-selected control points), the image is 
deformed.
+
+
+### Depth of control point
+
+There should be an option to adjust which part of overlapping mesh/image is visible – e.g. we have an image 
of a person (as in the picture below) and we want to move her arm so that it is in front of (or behind) her 
body.
+
+![File:Depth_of_control_point.png](Depth_of_control_point.png)
+
+Every control point has its depth which affects a part of mesh under the control point.
+
+User can change the depth using two buttons – one increases the depth, the other decreases it – or using two 
keys - which?.
+
+When more control points are selected, every one's depth is increased/decreased.
+
+## Mesh manipulation
+
+### Mesh visibility
+
+In some situations it's useful to see how the mesh looks like. User can toggle mesh visibility using a check 
button (or switch).
+
+### Mesh element size
+
+User can choose the size of mesh element (square) using a slider – but only before he starts adding control 
points. It is because of the fact that when changing mesh square size, we have to recreate 'source pose' and 
'destination pose' meshes. It's often impossible to recreate 'destination pose' mesh so that it looks 
similarly to previous 'destination pose' mesh.
+
+What would be a suitable name for this option? Density or precision?
+
+## Deformation control
+
+### Deformation algorithm control
+
+The deformation algorithm iteratively solves a least squares problem described in [the 
paper](http://dcgi.felk.cvut.cz/cgg/~sykorad/Sykora09-NPAR.pdf). During that process we periodically display 
current state of the solution and user can see that the deformation is evolving somehow. Usually hundreds of 
iterations are performed during 1 FPS. We don't know how much time the solving will take and at the same time 
we often don't want to find the final solution – we're interested just in the process.
+
+Hence there should be an option to temporary stop the process at some state or let it continue with solving 
further. How to do that in the best way? It could be done for example by `<space>` key.
+
+### Deformation termination
+
+When user is satisfied with result, he presses `<enter>` key. Deformed image is redrawn using selected 
interpolation method. The deformation ends.
+When user wants to cancel the deformation, he presses `<escape>` key. Deformed image is discarded, original 
image appears on the canvas. The deformation ends.
+
+## Undo/redo
+
+TODO
+
+## Settings
+
+### Deformation mode
+
+The method allows 3 types of deformation:
+
+* rigid (known as as-rigid-as-possible)
+* similar (known as as-similar-as-possible)
+* stretch (ARAP combined with weights from Moving Least Squares method)
+
+'Rigid' type is very good for bending objects or manipulating articulated objects. It's [not so good in 
stretching or shrinking of objects](http://www.youtube.com/watch?v=0_nl9fSTfMY&amp;t=0m05s). 'Similar' type 
allows changing of scale. Only translation, rotation and change of scale is included in deformation. It can 
be seen in [the example](http://www.youtube.com/watch?v=0_nl9fSTfMY&amp;t=1m26s). 'Stretch' type allows 
better stretching of objects. It can be seen in [the 
example](http://www.youtube.com/watch?v=0_nl9fSTfMY&amp;t=0m42s).
+
+User can select the deformation type using drop down list or radio buttons.
+
+
+### Number of deformation iterations
+
+User can select using slider, the number of iterations that are performed during 1 FPS. The larger the 
number the more rigid the deformation behaves.
+
+How to call this option? It can be called for example rigidity or flexibility.
+
+
+### Type of interpolation
+
+User can select the type of interpolation which is used when the deformation is terminated in favor of 
deformed image.
+
+Types of interpolation:
+
+
+* nearest neighbor (none)
+* linear
+* cubic
+* sinc
diff --git a/content/core/specifications/warp-tool.md b/content/core/specifications/warp-tool.md
new file mode 100644
index 0000000..a19734e
--- /dev/null
+++ b/content/core/specifications/warp-tool.md
@@ -0,0 +1,78 @@
+---
+title: "Warp tool: UI design info"
+Author: "GIMP team"
+Date: 2014-09-01
+lastmod: 2021-05-14
+---
+
+**NOTE: this is a document salvaged from our old wiki for a tool which
+is now available in stable versions. It should eventually be transformed
+into a proper specification with final UX choices.**
+
+## Idea and background
+
+A plugin named [iWarp](http://docs.gimp.org/2.6/en/plug-in-iwarp.html) already exists in Gimp, but suffer 
from different troubles (small preview, uneasy manipulation). This year’s Google Summer of Code have a 
project to implement this behavior as a real live on-canvas tool in Gimp. This project is taken by Michael 
Muré (batolettre gmail com, irc: Bat`O on #gimp irc gnome org).
+
+Basically, this would allow users to deform an image by a series of cursor action on it. This can be seen as 
a sort of sculpt. See for example the case where user can move pixel with a stroke of mouse. Others behavior 
can also be implemented, see below.
+
+## A quick technical sneak peek
+
+This tool will be a complete rewrite, no parts will be taken from the plugin. The tool will works with Gegl. 
The plugin can be seen as a proof of concept.
+
+Technically, this tool will work in two steps:
+
+* a series of tools, one by behavior, act on a image-sized buffer that hold relative coordinate for each 
pixel. That mean that each pixel of the final image will have on this buffer a coordinate from where the 
final color come from.
+* the final image is computed from the original image and this buffer.
+
+The approach with a coordinate buffer instead of acting directly on the image allows to:
+
+* Render the tool effect in a constant time, no matter the number of stroke.
+* No information lost. See for example the case of a pinch done multiple times in the same area so the input 
pixel would collapse. If you un-pinch the area, the map-absolute operator will fetch the right pixels, with 
no data loss.
+
+## Potential behavior
+
+This technical approach gives a good liberty when implementing behavior. Following is a list a potential 
behavior, but other can be found and implemented.
+
+* move: the stroke moves pixels under the cursor
+* swirl (left and right) - rotary transform
+* erase transform: cancel the transformation locally (ie set the relative coordinate to zero)
+* pinch/concentrate
+* expand
+* smooth: tend to flatten the transformation
+
+All operations are applied with a feathered "brush", so effect is largest at center and smallest at edge.
+
+## Tool options
+
+This tool would have as options at least:
+
+* size of the effect
+* shape of the effect (round or square ?) -i dont think offering other shapes than round provides much... 
[[User:AlexiaDeath|AlexiaDeath]] 20:41, 2 June 2011 (UTC)
+* Hardness of the effect (see hardness in round brushes)
+
+This part, as the others, need to be thought in details, an probably expanded.
+
+## Undo
+
+Undo should be achievable with this tool. What is exactly doable (one step undo ? more ?) is currently 
unclear and need to be discussed.
+
+Possible way to achieve that:
+
+* keeping copies of the coordinate buffer
+  * it will quickly eat a lot of memory
+* applying the stroke in reverse,
+  * it lead to approximation problem
+  * not all behavior are easy to undo (see for instance the cancel or smooth behavior)
+* recording all the stroke applied, and recomputing the coordinate buffer when undoing
+  * can take a lot of time if there is many strokes
+* mixed solution: keeping "keyframe" coordinate buffer, every n stroke + every strokes, and recompute from 
this keyframe when undoing
+* keeping modified tiles for every stroke done, and recompose a buffer when undoing
+* stack one gegl op for each stroke in a gegl graph to compute the final coordinate buffer, and unstack op 
for undo
+
+## Quality
+
+Since editing the coordinate buffer and rendering the transformation are two separated process, we can 
render the image with different quality without affecting the deformation.
+
+## Pressure sensitivity
+
+Options like the size of the effect or the sharpening of the shape could be pressure sensitive.