.. # define a hard line break for HTML
.. |br| raw:: html

   <br />


How to add a new processing?
----------------------------

This is done by deriving from :class:`StepFactory
<s1tiling.libs.steps.StepFactory>`, or from :class:`OTBStepFactory
<s1tiling.libs.steps.OTBStepFactory>`. You'll find many examples in the
default :ref:`step factories <Existing Processings>`.

The important points are to decide:

- Where should the step happen in the sequence of pipelines? |br|
  In all cases, don't forget to add it in a pipeline registered in the sequence
  of pipelines.
- Shall its result be considered as a public product, or an intermediary step?
  |br|
  A public product is expected to be always produced. It shall then conclude a
  :ref:`pipeline <Pipelines>`. Also, the pipeline shall be registered with
  ``product_required=True`` in that case.

- What would be the name of the result files? |br|
  Override :func:`build_step_output_filename()
  <s1tiling.libs.steps.StepFactory.build_step_output_filename>` with the
  answer.

  .. note::

      Even if there is no OTB application behind the step, this method needs to
      forward the filename of the input as done in
      :func:`AnalyseBorders.build_step_output_filename()
      <s1tiling.libs.otbwrappers.AnalyseBorders.build_step_output_filename>`.

- Which configuration options would be needed? |br|
  Copy them from the constructor that will be passed the
  :class:`s1tiling.libs.configuration.Configuration` object.
- What meta information should be filled-in? |br|
  This should be done in :func:`complete_meta()
  <s1tiling.libs.steps.StepFactory.complete_meta>`. |br|
  Meta information can be used:

  - immediately by other methods like :func:`parameters()
    <s1tiling.libs.steps._FileProducingStepFactory.parameters>`,
  - or by later steps in the pipeline.
- If there is an OTB application behind the step -- which should be the case
  for most processing steps.

In case the step relates to an OTB application:

- What parameters shall be sent to the OTB application? |br|
  Return the information from :func:`parameters()
  <s1tiling.libs.steps._FileProducingStepFactory.parameters>`.
- What are the parameters expected by the OTB application from the images that
  could be passed in-memory? |br|
  The default are ``"in"`` and ``"out"`` but could be overridden in the
  constructor of the new step factory through the parameters ``param_in`` and
  ``param_out``. See for instance
  :func:`s1tiling.libs.otbwrappers.OrthoRectify.__init__` implementation.
- What is the OTB application? |br|
  Its name is expected to be passed to the constructor of the parent class,
  from the constructor of the new class.

.. note::

    Most of the time, inheriting of :class:`OTBStepFactory
    <s1tiling.libs.steps.OTBStepFactory>` is the best choice. Still, it's
    possible to take over and to manually answer the following questions:

    - What would be the name of the temporary files while they are being produced? |br|
      Return the information from :func:`build_step_output_tmp_filename()
      <s1tiling.libs.steps.StepFactory.build_step_output_tmp_filename>`,
    - Where the product should be produced? |br|
      Return the information from :func:`output_directory()
      <s1tiling.libs.steps._FileProducingStepFactory.output_directory>` -- this is
      typically used from :func:`build_step_output_filename()
      <s1tiling.libs.steps.StepFactory.build_step_output_filename>`.

Technically all other methods from :class:`StepFactory
<s1tiling.libs.steps.StepFactory>` could be overridden. For instance,
:func:`create_step() <s1tiling.libs.steps.StepFactory.create_step>` could
be overridden to change the type of :ref:`Steps` instantiated.