Module org.scijava.ops.api
Package org.scijava.ops.api

Interface OpEnvironment

  • All Superinterfaces:
    Comparable<OpEnvironment>, Prioritized<OpEnvironment>
    public interface OpEnvironment
extends Prioritized<OpEnvironment>
    An op environment is the top-level entry point into op execution. It provides all the built-in functionality of ops in a single place, including:
    • The pool of available ops, from which candidates are chosen.
    • Type-safe, built-in method signatures for all op implementations.
    • Selection (a.k.a. "matching") of op implementations from OpRequest descriptors.

    Customizing the OpEnvironment allows customization of any or all of the above. Potential use cases include:

    • Limiting or extending the pool of available op implementations.
    • Caching op outputs to improve subsequent time performance.
    • Configuration of environment "hints" to improve performance in time or space.
    Author:
    Curtis Rueden, Gabriel Selzer

    • Method Detail

      • discoverUsing

        void discoverUsing​(Discoverer... d)

      • discoverEverything

        void discoverEverything()

      • op

        default <T> T op​(String opName,
                 Nil<T> specialType,
                 Nil<?>[] inTypes,
                 Nil<?> outType)
        Returns an Op fitting the provided arguments. NB implementations of this method likely depend on the Hints set by setDefaultHints(Hints), which provides no guarantee of thread-safety. Users interested in parallel Op matching should consider using op(String, Nil, Nil[], Nil, Hints) instead.
        Type Parameters:
        T - the Type of the Op
        Parameters:
        opName - the name of the Op
        specialType - the generic Type of the Op
        inTypes - the arguments (inputs) to the Op
        outType - the return of the Op (note that it may also be an argument)
        Returns:
        an instance of an Op aligning with the search parameters

      • op

        <T> T op​(String opName,
         Nil<T> specialType,
         Nil<?>[] inTypes,
         Nil<?> outType,
         Hints hints)
        Returns an Op fitting the provided arguments.
        Type Parameters:
        T - the Type of the Op
        Parameters:
        opName - the name of the Op
        specialType - the generic Type of the Op
        inTypes - the arguments (inputs) to the Op
        outType - the return of the Op (note that it may also be an argument)
        hints - the Hints that should guide this matching call
        Returns:
        an instance of an Op aligning with the search parameters

      • opFromInfoTree

        default <T> T opFromInfoTree​(InfoTree tree,
                             Nil<T> specialType)

      • opFromInfoTree

        <T> T opFromInfoTree​(InfoTree tree,
                     Nil<T> specialType,
                     Hints hints)

      • opFromSignature

        default <T> T opFromSignature​(String signature,
                              Nil<T> specialType)
        Returns an Op fitting the provided arguments.
        Type Parameters:
        T - the Type of the Op
        Parameters:
        signature - the signature of the Op
        specialType - the generic Type of the Op
        Returns:
        an instance of an Op aligning with the search parameters

      • op

        default OpBuilder op​(String opName)

        Entry point for convenient Op calls, providing a builder-style interface to walk through the process step-by-step.

        The general order of specification:

        1. The op name (and Hints, if desired)
        2. The number of input(s)
        3. The type or value(s) of input(s)
        4. One of:
          • The type or value of the output
          • Which input should be modified in-place
        The first two steps are required, at a minimum. The choices you make will determine the type of Op that is matched:
        • No inputs → Producer or Computer
        • Inputs with an output value → Computer
        • Inputs with an output type → Computer or Function
        • Inputs with no output → Inplace or Function with unknown (Object) return

        Examples: OpEnvironment env = new DefaultOpEnvironment();

        • env.op("create").outType(DoubleType.class).create(); — run an Op creating an instance of the ImgLib2 DoubleType
        • env.op("create").outType(DoubleType.class).create(); — same as above.
        • env.op("create", hints).outType(DoubleType.class).create(); — same as above but matching with the provided Hints.
        • env.op("create").outType(Img.class).create(); — run an Op creating a raw instance of an ImgLib2 Img.
        • env.op("create").outType(new Nil<Img<DoubleType>>(){}).create(); — run an Op creating an instance of an ImgLib2 Img<DoubleType>.
        • env.op("math.add").inType(Integer.class, Integer.class).function(); — get an instance of an Op to add two integers together. Return type will be Object.
        • env.op("math.add").inType(Integer.class, Integer.class).function(); — same as above.
        • env.op("math.add").input(1, 1).outType(Double.class).apply(); — run an Op combining two integers. Return type will be Double.
        • env.op("math.add").input(img1, img2).output(result).compute(); — run an Op combining two images and storing the result in a pre-allocated image.
        • env.op("filter.addPoissonNoise").input(img1).mutate(); — run an Op adding poisson noise to an input image.
        Parameters:
        opName - The name of the Op to run
        Returns:
        The OpBuilder instance for builder chaining.
        Throws:
        OpMatchingException - if the Op request cannot be satisfied
        See Also:
        To specify a Hints instance to use, OpBuilder

      • genericType

        Type genericType​(Object obj)
        Discerns the generic type of an object instance.

      • typeLambda

        <T> T typeLambda​(Nil<T> opType,
                 T lambda)
        Enriches a lambda expression with its generic type. Its usage is necessary in order to find Ops that could take this lamdba expression as an argument.

        Suppose, for example, that a user has a lambda expression of type Function<Double, Double>, and they wish to use the engine.adapt Op to transform it into a Function<Iterable<Double>, Iterable<Double>>. Naively, they write: 

        
 Function<Double, Double> doubler = x -> 2*x;
 Function<Iterable<Double>, Iterable<Double>> iterableDoubler =
   ops.op("engine.adapt").input(doubler).outType(new Nil<>() {}).apply();
        but it does not work, because the Ops engine cannot know the generic type of the doubler object. One workaround is to specify the input generic type explicitly: 
        
 Function<Double, Double> doubler = x -> 2*x;
 Function<Iterable<Double>, Iterable<Double>> iterableDoubler =
   ops.op("engine.adapt")
     .inType(new Nil<Function<Double, Double>() {})
     .outType(new Nil<>() {}).function().apply(doubler);
        Another approach is to use this typeLambda method as follows: 
        
 Function<Double, Double> doubler = ops.typeLambda(new Nil<>() {}, x -> 2*x);
 Function<Iterable<Double>, Iterable<Double>> iterableDoubler =
   ops.op("engine.adapt").input(doubler).outType(new Nil<>() {}).apply();
        In the above example, the doubler object returned by typeLambda has its generic type information embedded, rather than being a raw lambda where the generic type information is erased at runtime.

        Note: typeLambda does not need to be used with anonymous subclasses; these already retain their type parameters at runtime. It is only lambda expressions that need to be passed to this method.

        Type Parameters:
        T - The lambda's functional type (e.g. Function<String, Double>)
        Parameters:
        opType - The generic type of the lambda expression to be embedded. (e.g. new Nil<Function<String, Double>>() {})
        lambda - A lambda expression fulfilling the functional interface contract of the stated opType.
        Returns:
        An enriched version of the lambda object that embeds knowledge of its generic type by implementing the GenericTyped interface.

      • opify

        default OpInfo opify​(Class<?> opClass,
                     String... names)
        Creates an OpInfo from a Class.
        Parameters:
        opClass - the Class from which to derive the Op
        names - the name(s) of the Op
        Returns:
        an OpInfo which can make instances of opClass

      • opify

        OpInfo opify​(Class<?> opClass,
             double priority,
             String... names)
        Creates an OpInfo from a Class with the given priority.
        Parameters:
        opClass - the Class from which to derive the Op
        priority - the assigned priority of the Op.
        names - the name(s) of the Op
        Returns:
        an OpInfo which can make instances of opClass

      • getDefaultHints

        Hints getDefaultHints()
        Returns a copy of the default Hints object.
        Returns:
        the default Hints

      • help

        default String help()
        Returns the descriptions for all Ops contained within this OpEnvironment
        Returns:
        a String describing all Ops in the environment matching name

      • help

        default String help​(String name)
        Returns the descriptions for all Ops contained within this OpEnvironment matching name
        Parameters:
        name - the String name to filter on
        Returns:
        a String describing all Ops in the environment matching name

      • help

        String help​(OpRequest request)
        Returns simple descriptions for all Ops identifiable by a given name within this OpEnvironment
        Parameters:
        request - the OpRequest to filter on
        Returns:
        a String containing a (set of) lines for each Op matching request

      • helpVerbose

        default String helpVerbose()
        Returns verbose descriptions for all Ops contained within this OpEnvironment
        Returns:
        a String containing a (set of) lines for each Op

      • helpVerbose

        default String helpVerbose​(String name)
        Returns verbose descriptions for all Ops contained within this OpEnvironment
        Parameters:
        name - the String name to filter on
        Returns:
        a String describing all Ops in the environment matching name

      • helpVerbose

        String helpVerbose​(OpRequest request)
        Returns verbose descriptions for all Ops contained within this OpEnvironment
        Parameters:
        request - the OpRequest to filter on
        Returns:
        a String containing a (set of) lines for each Op matching request