4242 * calls with just one implementation. The simplest type of transformation is
4343 * showcased in {@link OpAdaptation}.
4444 * <p>
45- * A more complex type of transformation is called "simplification". This type
46- * involves transforming some subset of Op inputs into a different, but similar
47- * type. This process makes use of three different Op types:
45+ * A more complex transformation, termed parameter "conversion", alters
46+ * individual Op parameter types. Parameter conversion makes use of two
47+ * different Op types:
4848 * <ul>
49- * <li>"engine.convert" Ops transform user inputs into a broader data type</li>
50- * <li>"engine.focus" Ops transform that broader type into the type used by the
51- * Op</li>
52- * <li>"engine.copy" Ops are necessary to propagate changes to the simplified
53- * type back to the original parameter</li>
49+ * <li>{@code engine.convert} Ops transform user inputs into a different data
50+ * type</li>
51+ * <li>{@code engine.copy} Ops propagate changes to mutable Op parameters back
52+ * into the user's output buffers.</li>
5453 * </ul>
5554 * <p>
56- * Simplification can be used to call a method implemented for parameters of one
57- * type on a completely different type. This can be as simple as using an
58- * Integer instead of a Double, or go beyond the Java type assignability with
59- * custom defined type conversion (e.g. images from one library to another).
55+ * Conversion can be used to call an Op using parameters of completely different
56+ * types. This can be as simple as using an Integer instead of a Double, or go
57+ * beyond Java type assignment rules with custom defined type conversion (e.g.
58+ * images from one library to another). When this happens, the following steps
59+ * are taken:
60+ * <ol>
61+ * <li>All inputs are converted to types required by the Op, using
62+ * {@code engine.convert} "preconverter" Ops.</li>
63+ * <li>The Op is invoked on the converted inputs</li>
64+ * <li>If the Op defines a <em>pure</em> output object, that output is converted
65+ * to the user's requested type using a {@code engine.convert} "postconverter"
66+ * Op</li>
67+ * <li>If the Op defines a <em>mutable</em> output object (i.e. a pre-allocated
68+ * output buffer), the converted pre-allocated output buffer is copied back into
69+ * the user's pre-allocated output buffer using a {@code engine.copy} Op.</li>
70+ * </ol>
6071 * <p>
61- * Below, we can see how this works by calling the above Field Op, implemented
62- * for Double, on a Double[] instead
72+ * Below, we can see how this works by calling the below Field Op, implemented
73+ * for {@link Double}s, with {@link Integer} arguments
6374 */
64- public class OpSimplification implements OpCollection {
75+ public class OpConversion implements OpCollection {
6576
6677 /**
6778 * A simple Op, written as a {@link Field}, that performs a simple
6879 * calculation.
6980 */
70- @ OpField (names = "tutorial.simplify " )
81+ @ OpField (names = "tutorial.conversion " )
7182 public final BiFunction <Double , Double , Double > fieldOp = (a , b ) -> {
7283 return a * 2 + b ;
7384 };
@@ -78,8 +89,8 @@ public static void main(String... args) {
7889 // Call the Op on some inputs
7990 Integer first = 1 ;
8091 Integer second = 2 ;
81- // Ask for an Op of name "tutorial.simplify "
82- Integer result = ops .binary ("tutorial.simplify " ) //
92+ // Ask for an Op of name "tutorial.conversion "
93+ Integer result = ops .binary ("tutorial.conversion " ) //
8394 // With our two Integer inputs
8495 .input (first , second ) //
8596 // And get an Integer out
@@ -89,22 +100,22 @@ public static void main(String... args) {
89100 .apply ();
90101
91102 /*
92- The simplification routine works as follows:
93- 1. SciJava Ops determines that there are no existing "tutorial.simplify" Ops
94- that work on Integers
103+ The conversion routine works as follows:
104+ 1. SciJava Ops determines that there are no existing "tutorial.conversion"
105+ Ops that work on Integers
95106
96- 2. SciJava Ops finds a "engine.focus " Op that can make Doubles from Numbers. Thus,
97- if the inputs are Numbers , SciJava Ops could use this "engine.focus" Op to make
98- those Numbers into Doubles
107+ 2. SciJava Ops finds an "engine.convert " Op that can make Doubles from
108+ Integers. Thus, if the inputs are Integers , SciJava Ops could use this
109+ "engine.convert" Op to make those Integers into Doubles
99110
100- 3 . SciJava Ops finds a "engine.convert" Op that can make Numbers from Integers.
101- Thus, if the inputs are Integers , SciJava Ops can use this "engine.convert" Op
102- to make those Integers into Numbers
111+ 2 . SciJava Ops finds an "engine.convert" Op that can make Integers from
112+ Doubles. Thus, if a Double output is requested , SciJava Ops could use this
113+ "engine.convert" Op to make a Double output from an Integer
103114
104- 4 . By using the "engine.convert" and then the "engine.focus" Op , SciJava Ops can convert
105- the Integer inputs into Double inputs, and by creating a similar chain
106- in reverse, can convert the Double output into an Integer output.
107- Thus, we get an Op that can run on Integers!
115+ 3 . By using the "engine.convert" Ops , SciJava Ops can convert each of
116+ the Integer inputs into Double inputs, and then can convert the Double
117+ output back into the Integer the user requested. Thus, we get an Op that can
118+ run on Integers!
108119 */
109120 System .out .println (result );
110121
0 commit comments