[gimp-help] Add distort/spherize.xml

[Julien Hardlin <jhardlin src gnome org>]

commit fe43f5483370ee6ae98b41e8c6b42328af30b457
Author: Julien Hardelin <jhardlin orange fr>
Date:   Sat Dec 22 08:03:11 2018 +0100

    Add distort/spherize.xml

 images/C/filters/distort/spherize-dialog.png       | Bin 0 -> 24707 bytes
 .../filters/examples/distort/spherize-defaults.jpg | Bin 0 -> 48093 bytes
 .../examples/distort/spherize-ex-amount.jpg        | Bin 0 -> 41116 bytes
 .../filters/examples/distort/spherize-ex-angle.jpg | Bin 0 -> 38452 bytes
 .../examples/distort/spherize-ex-curvature.jpg     | Bin 0 -> 41140 bytes
 .../examples/distort/spherize-ex-horizontal.jpg    | Bin 0 -> 40258 bytes
 .../filters/examples/distort/spherize-ex-orig.jpg  | Bin 0 -> 51732 bytes
 .../examples/distort/spherize-ex-sphere.jpg        | Bin 0 -> 20669 bytes
 src/filters/distort.xml                            |   2 +-
 src/filters/distort/spherize.xml                   | 207 +++++++++++++++++++++
 10 files changed, 208 insertions(+), 1 deletion(-)
---
diff --git a/images/C/filters/distort/spherize-dialog.png b/images/C/filters/distort/spherize-dialog.png
new file mode 100644
index 000000000..8ea606023
Binary files /dev/null and b/images/C/filters/distort/spherize-dialog.png differ
diff --git a/images/C/filters/examples/distort/spherize-defaults.jpg 
b/images/C/filters/examples/distort/spherize-defaults.jpg
new file mode 100644
index 000000000..e4e429b11
Binary files /dev/null and b/images/C/filters/examples/distort/spherize-defaults.jpg differ
diff --git a/images/C/filters/examples/distort/spherize-ex-amount.jpg 
b/images/C/filters/examples/distort/spherize-ex-amount.jpg
new file mode 100644
index 000000000..f7ef25e96
Binary files /dev/null and b/images/C/filters/examples/distort/spherize-ex-amount.jpg differ
diff --git a/images/C/filters/examples/distort/spherize-ex-angle.jpg 
b/images/C/filters/examples/distort/spherize-ex-angle.jpg
new file mode 100644
index 000000000..934fb1fb6
Binary files /dev/null and b/images/C/filters/examples/distort/spherize-ex-angle.jpg differ
diff --git a/images/C/filters/examples/distort/spherize-ex-curvature.jpg 
b/images/C/filters/examples/distort/spherize-ex-curvature.jpg
new file mode 100644
index 000000000..1f7788626
Binary files /dev/null and b/images/C/filters/examples/distort/spherize-ex-curvature.jpg differ
diff --git a/images/C/filters/examples/distort/spherize-ex-horizontal.jpg 
b/images/C/filters/examples/distort/spherize-ex-horizontal.jpg
new file mode 100644
index 000000000..dc442ffa8
Binary files /dev/null and b/images/C/filters/examples/distort/spherize-ex-horizontal.jpg differ
diff --git a/images/C/filters/examples/distort/spherize-ex-orig.jpg 
b/images/C/filters/examples/distort/spherize-ex-orig.jpg
new file mode 100644
index 000000000..90cebc340
Binary files /dev/null and b/images/C/filters/examples/distort/spherize-ex-orig.jpg differ
diff --git a/images/C/filters/examples/distort/spherize-ex-sphere.jpg 
b/images/C/filters/examples/distort/spherize-ex-sphere.jpg
new file mode 100644
index 000000000..cd20d7de3
Binary files /dev/null and b/images/C/filters/examples/distort/spherize-ex-sphere.jpg differ
diff --git a/src/filters/distort.xml b/src/filters/distort.xml
index e677c716b..138b52ea5 100644
--- a/src/filters/distort.xml
+++ b/src/filters/distort.xml
@@ -24,7 +24,7 @@
   <xi:include href="distort/polarcoords.xml"/>
   <xi:include href="distort/ripple.xml"/>
   <xi:include href="distort/shift.xml"/>
-  <!--<xi:include href="distort/spherize.xml"/>-->
+  <xi:include href="distort/spherize.xml"/>
   <xi:include href="distort/vpropagate.xml"/>
   <xi:include href="distort/video.xml"/>
   <xi:include href="distort/waves.xml"/>
diff --git a/src/filters/distort/spherize.xml b/src/filters/distort/spherize.xml
new file mode 100644
index 000000000..28c1661e9
--- /dev/null
+++ b/src/filters/distort/spherize.xml
@@ -0,0 +1,207 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                       "http://www.docbook.org/xml/4.3/docbookx.dtd";>
+<!-- section history:
+  2018-12-18 j.h: create
+-->
+
+<sect2 id="gimp-filter-spherize">
+  <title>Spherize</title>
+  <indexterm>
+    <primary>filters</primary>
+    <secondary>Distorts</secondary>
+  </indexterm>
+  <indexterm>
+    <primary>Spherize</primary>
+  </indexterm>
+
+  <sect3>
+    <title>Overview</title>
+    <para>
+      This filter creates a kind of bubble whose size is that of the image or 
+      selection, as if the content was wrapped around a sphere.
+    </para>
+    <figure>
+      <title>Spherize filter example, with default values</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata format="JPG"
+            fileref="images/filters/examples/distort/spherize-ex-orig.jpg"/>
+        </imageobject>
+        <caption>
+          <para>Original image</para>
+        </caption>
+      </mediaobject>
+      <mediaobject>
+        <imageobject>
+          <imagedata format="JPG"
+            fileref="images/filters/examples/distort/spherize-defaults.jpg"/>
+        </imageobject>
+        <caption>
+          <para><quote>Spherize</quote> filter applied</para>
+        </caption>
+      </mediaobject>
+    </figure>
+  </sect3>
+  
+  <sect3>
+    <title>Starting filter</title>
+    <para>
+      You can find this filter through
+      <menuchoice>
+        <guimenu>Filters</guimenu>
+        <guisubmenu>Distorts</guisubmenu>
+        <guimenuitem>Spherize…</guimenuitem>
+      </menuchoice>
+    </para>
+  </sect3>
+  
+  <sect3>
+    <title>Options</title>
+    <figure>
+      <title><quote>Spherize</quote> filter options</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata format="PNG"
+            fileref="images/filters/distort/spherize-dialog.png"/>
+        </imageobject>
+      </mediaobject>
+    </figure>
+    
+    <variablelist>
+      <varlistentry>
+        <term><guilabel>Presets</guilabel>, <guilabel>Preview</guilabel>, 
+          <guilabel>Split view</guilabel></term>
+        <listitem>
+          <para>
+            These options are common to GEGL-based filters. Please refer to 
+            <xref linkend="gimp-filters-common"/>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Mode</guilabel></term>
+        <listitem>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <emphasis role = "bold">Radial</emphasis> is the default mode. 
+                See example above.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <emphasis role = "bold">Horizontal</emphasis>: as if image was 
+                mapped on a <emphasis role="underline">vertical</emphasis> 
+                cylinder.
+              </para>
+              <mediaobject>
+                <imageobject>
+                  <imagedata format="JPG"
+          fileref="images/filters/examples/distort/spherize-ex-horizontal.jpg"/>
+                </imageobject>
+              </mediaobject>
+            </listitem>
+            <listitem>
+              <para>
+                <emphasis role = "bold">Vertical</emphasis>: as if image was 
+                mapped on a <emphasis role="underline">horizontal</emphasis> 
+                cylinder.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Angle of view</guilabel></term>
+        <listitem>
+          <para>
+            Camera angle of view (0 - 180°)
+          </para>
+          <mediaobject>
+            <imageobject>
+              <imagedata format="JPG"
+              fileref="images/filters/examples/distort/spherize-ex-angle.jpg"/>
+            </imageobject>
+          </mediaobject>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Curvature</guilabel></term>
+        <listitem>
+          <para>
+            Spherical cap angle, as a faction of the co-angle (complement 
+            angle) of view. Result is less domed as curvature decreases 
+            (100% - 0).
+            </para>
+          <mediaobject>
+            <imageobject>
+              <imagedata format="JPG"
+          fileref="images/filters/examples/distort/spherize-ex-curvature.jpg"/>
+            </imageobject>
+          </mediaobject>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Amount</guilabel></term>
+        <listitem>
+          <para>
+            Interesting for negative values, which result in a hollow instead 
+            of a bump (from 1.000 to -1.000).
+            </para>
+          <mediaobject>
+            <imageobject>
+              <imagedata format="JPG"
+              fileref="images/filters/examples/distort/spherize-ex-amount.jpg"/>
+            </imageobject>
+          </mediaobject>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Resampling methods</guilabel></term>
+        <listitem>
+          <para>
+            These interpolation methods are described in 
+            <xref linkend="gimp-tool-interpolation-methods"/>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Use the selection as input</guilabel></term>
+        <listitem>
+          <para>
+            If this option is selected, the filter uses pixels in selection 
+            only.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><guilabel>Use the entire layer as input</guilabel></term>
+        <listitem>
+          <para>
+            If this option is selected, the filter uses pixels adjacent to the 
+            selection to create a more progressive border.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </sect3>
+  <sect3>
+    <title>Using Spherize filter</title>
+    <para>
+      Drawing a selection before applying filter allows you to create another 
+      shape, such as a sphere: select Ellipse tool with the 
+      <guilabel>Fixed</guilabel> option checked; draw a circle; apply Spherize 
+      filter with the <guilabel>Use the selection as input</guilabel> selected. 
+      Invert selection and fill it with wanted background.
+    </para>
+    <mediaobject>
+      <imageobject>
+        <imagedata format="JPG"
+          fileref="images/filters/examples/distort/spherize-ex-sphere.jpg"/>
+      </imageobject>
+    </mediaobject>
+  </sect3>
+</sect2>
+
+