otbBandMathX.cxx 10.9 KB
Newer Older
Christophe Palmann's avatar
Christophe Palmann committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
/*=========================================================================

 Program:   ORFEO Toolbox
 Language:  C++
 Date:      $Date$
 Version:   $Revision$


 Copyright (c) Centre National d'Etudes Spatiales. All rights reserved.
 See OTBCopyright.txt for details.


 This software is distributed WITHOUT ANY WARRANTY; without even
 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE.  See the above copyright notices for more information.

 =========================================================================*/
#include "otbWrapperApplication.h"
#include "otbWrapperApplicationFactory.h"

#include "otbObjectList.h"

23
#include "otbBandMathXImageFilter.h"
Christophe Palmann's avatar
Christophe Palmann committed
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

namespace otb
{

namespace Wrapper
{

class BandMathX : public Application
{

public:
  /** Standard class typedefs. */
  typedef BandMathX                      Self;
  typedef Application                    Superclass;
  typedef itk::SmartPointer<Self>        Pointer;
  typedef itk::SmartPointer<const Self> ConstPointer;

  /** Standard macro */
  itkNewMacro(Self);

  itkTypeMacro(BandMathX, otb::Application);


47
  typedef otb::BandMathXImageFilter<FloatVectorImageType>                             BandMathImageFilterType;
Christophe Palmann's avatar
Christophe Palmann committed
48 49 50 51 52 53


private:
  void DoInit()
  {
    SetName("BandMathX");
54 55
    SetDescription("This application performs mathematical operations on multiband images.\n"
      "Mathematical formula interpretation is done via muParserX libraries https://code.google.com/p/muparserx/");
Christophe Palmann's avatar
Christophe Palmann committed
56 57

    SetDocName("Band Math X");
58 59 60 61 62 63 64
    SetDocLongDescription("The goal of this documentation is to give the user some hints about the syntax used in this application.\n"
      "The syntax is mainly constrained by the muparserx library, which can be considered as the core of the application.\n"
      "\n\n"
      "- Fundamentals:\n\n"
      "The default prefix name for variables related to the ith input is « im(i+1) » (note the indexing from 1 to N, for N inputs). \n"
      "The following list summaries the available variables for input #0 (and so on for every input): \n"
      "\n"
65 66 67 68 69
      "im1                                -->   a pixel from first input, made of n components (n bands)\n"
      "im1bj                             -->   jth component of a pixel from first input (first band is indexed by 1)\n"
      "im1bjNkxp                     -->   a neighbourhood (“N”) of pixels of the jth component from first input, of size kxp\n"
      "im1PhyX and im1PhyY  -->   spacing of first input in X and Y directions (horizontal and vertical)\n"
      "im1bjMean im1bjMin im1bjMax im1bjSum im1bjVar  -->   mean, min, max, sum, variance of jth band from first input (global statistics)\n"
70 71 72 73 74 75
      "\nMoreover, we also have the following generic variables:\n"
      "idxX and idxY        -->   indices of the current pixel\n"
      "\n"
      "Always keep in mind that this application only addresses mathematically well-defined formulas.\n"
      "For instance, it is not possible to add vectors of different dimensions (this implies the addition of a row vector with a column vector),\n"
      "or add a scalar to a vector or a matrix, or divide two vectors, and so on...\n"
OTB Bot's avatar
STYLE  
OTB Bot committed
76
      "Thus, it is important to remember that a pixel of n components is always represented as a row vector.\n"
77 78
      "\n"
      "Example :\n\n"
79
      "                   im1 + im2       (1)\n"
80 81 82 83 84
      "\nrepresents the addition of pixels from first and second inputs. This expression is consistent only if\n"
      "both inputs have the same number of bands.\n"
      "Note that it is also possible to use the following expressions to obtain the same result:\n"
      "\n"
      "                   im1b1 + im2b1 \n"
85
      "                   im1b2 + im2b2       (2)\n"
86 87
      "                         ...."
      "\n\nNevertheless, the first expression is by far much pleaseant. We call this new functionnality the 'batch mode'\n"
OTB Bot's avatar
STYLE  
OTB Bot committed
88
      "(performing the same operation in a band-to-band fashion).\n"
89 90 91 92 93

      "\n\n"
      "- Operations involving neighborhoods of pixels:\n\n"
      "Another new fonctionnality is the possibility to perform operations that involve neighborhoods of pixels.\n"
      "Variable related to such neighborhoods are always defined following the pattern imIbJNKxP, where: \n"
94
      "- I is an number identifying the image input (remember, input #0 = im1, and so on)\n"
95 96 97 98 99
      "- J is an number identifying the band (remember, first band is indexed by 1)\n"
      "- KxP are two numbers that represent the size of the neighborhood (first one is related to the horizontal direction)\n"
      "All neighborhood are centred, thus K and P must be odd numbers.\n"
      "Many operators come with this new functionnality: conv, mean var median min max...\n"
      "For instance, if im1 represents the pixel of 3 bands image:\n\n"
100
      "               im1 - mean(im1b1N5x5,im1b2N5x5,im1b3N5x5)       (3)\n"
101
      "\ncould represent a high pass filter (Note that by implying three neighborhoods, the operator returned a row vector of three components.\n"
102
      "It is a typical behaviour for many operators of this application).\n"
103 104 105 106 107

      "\n\n"
      "- Operators:\n\n"
      "In addition to the previous operators, other operators are available:\n"
      "- existing operators/functions from muParserX, that were not originally defined for vectors and\n"
108 109 110
      "matrices (for instance cos, sin, ...). These new operators/ functions keep the original names to which we added the prefix ”v” for vector (vcos, vsin, ...).\n"
      "- mult, div and pow operators, that perform element-wise multiplication, division or exponentiation of vector/matrices (for instance im1 div im2)\n"
      "- mlt, dv and pw operators, that perform multiplication, division or exponentiation of vector/matrices by a scalar (for instance im1 dv 2.0)\n"
111 112 113
      "- bands, which is a very usefull operator. It allows to select specific bands from an image, and/or to rearrange them in a new vector;\n"
      "for instance bands(im1,{1,2,1,1}) produces a vector of 4 components made of band 1, band 2, band 1 and band 1 values from the first input.\n"
      "Note that curly brackets must be used in order to select the desired band indices.\n"
114
      "... and so on.\n"
115 116 117

      "\n\n"
      "- Application itself:\n\n"
118 119
      "The application takes the following parameters :"
      "- Setting the list of inputs can be done with the 'il' parameter.\n"
OTB Bot's avatar
STYLE  
OTB Bot committed
120
      "- Setting expressions can be done with the 'exp' parameter. Separating expressions by semi-colons (; ) will concatenate their results into one multiband output image.\n"
121
      "Adding expressions without the use of semi-colons will produce additional output images.\n"
122 123 124
      "- Setting constants can be done with the 'incontext' parameter. User must provide a txt file with a specific syntax: #type name value\n"
      "An example of such a file is given below:\n\n"
      "#F expo 1.1\n"
OTB Bot's avatar
STYLE  
OTB Bot committed
125
      "#M kernel1 { 0.1 , 0.2 , 0.3; 0.4 , 0.5 , 0.6; 0.7 , 0.8 , 0.9; 1 , 1.1 , 1.2; 1.3 , 1.4 , 1.5 }\n"
126
      "\nAs we can see,  #I/#F allows the definition of an integer/float constant, whereas #M allows the definition of a vector/matrix.\n"
Christophe Palmann's avatar
Christophe Palmann committed
127
      "In the latter case, elements of a row must be separated by commas, and rows must be separated by semicolons.\n"
128
      "It is also possible to define expressions within the same txt file, with the pattern #E expr; they will be added to the list of expressions to be applied. For instance:\n\n"
OTB Bot's avatar
STYLE  
OTB Bot committed
129
      "#E conv(kernel1,im1b1N3x5); im2b1^expo\n"
130 131
      "\n- The 'outcontext' parameter allows to save user's constants and expressions (context).\n"
      "- Setting the output image can be done with the 'out' parameter (multi-outputs is not implemented yet).\n"
132
      "\n\n"
133
      "Finally, we strongly recommend that the reader takes a look at the cookbook, where additional information can be found (http://www.orfeo-toolbox.org/packages/OTBCookBook.pdf).\n"
134 135 136 137

);

    SetDocLimitations("Only one output is possible (to be improved)");
Christophe Palmann's avatar
Christophe Palmann committed
138 139 140 141 142 143 144 145 146 147 148 149
    SetDocAuthors("OTB-Team");
    SetDocSeeAlso(" ");
    AddDocTag("Util");

    AddParameter(ParameterType_InputImageList,  "il",   "Input image list");
    SetParameterDescription("il", "Image list to perform computation on.");

    AddParameter(ParameterType_OutputImage, "out", "Output Image");
    SetParameterDescription("out","Output image.");

    AddRAMParameter();

150
    AddParameter(ParameterType_StringList, "exp", "Expressions");
Christophe Palmann's avatar
Christophe Palmann committed
151
    SetParameterDescription("exp",
152
                            "Mathematical expressions to apply.");
153 154
    MandatoryOff("exp");

155
    AddParameter(ParameterType_InputFilename, "incontext", "Import context");
156 157 158 159
    SetParameterDescription("incontext",
                            "A txt file containing user's constants and expressions.");
    MandatoryOff("incontext");

160
    AddParameter(ParameterType_OutputFilename, "outcontext", "Export context");
161
    SetParameterDescription("outcontext",
162
                            "A txt file where to save user's constants and expressions.");
163
    MandatoryOff("outcontext");
Christophe Palmann's avatar
Christophe Palmann committed
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184

    // Doc example parameter settings
    SetDocExampleParameterValue("il", "verySmallFSATSW_r.tif verySmallFSATSW_nir.tif verySmallFSATSW.tif");
    SetDocExampleParameterValue("out", "apTvUtBandMathOutput.tif");
    SetDocExampleParameterValue("exp", "\"cos(im1b1)+im2b1*im3b1-im3b2+ndvi(im3b3, im3b4)\"");
  }

  void DoUpdateParameters()
  {

  }

  void DoExecute()
  {
    // Get the input image list
    FloatVectorImageListType::Pointer inList = GetParameterImageList("il");

    // checking the input images list validity
    const unsigned int nbImages = inList->Size();

    if (nbImages == 0)
185 186 187 188
    {
     itkExceptionMacro("No input Image set...; please set at least one input image");
    }

189
    if ( (!IsParameterEnabled("exp")) && (!IsParameterEnabled("incontext")) )
190
    {
191
     itkExceptionMacro("No expression set...; please set and enable at least one one expression");
192
    }
Christophe Palmann's avatar
Christophe Palmann committed
193

194 195
    m_Filter               = BandMathImageFilterType::New();

Christophe Palmann's avatar
Christophe Palmann committed
196 197 198 199 200 201 202 203 204 205 206 207 208
    for (unsigned int i = 0; i < nbImages; i++)
      {
        FloatVectorImageType::Pointer currentImage = inList->GetNthElement(i);
        currentImage->UpdateOutputInformation();

        otbAppLogINFO( << "Image #" << i + 1 << " has "
                       << currentImage->GetNumberOfComponentsPerPixel()
                       << " components" << std::endl );

        m_Filter->SetNthInput(i,currentImage);

      }

209

210
    if ( IsParameterEnabled("exp") )
211 212 213
    {
      std::vector<std::string> stringList = GetParameterStringList("exp");
      for(int s=0; s<stringList.size(); s++)
214 215 216 217
        {
          otbAppLogINFO( << stringList[s] << std::endl );
          m_Filter->SetExpression(stringList[s]);
        }
218 219
    }

220
    if ( IsParameterEnabled("incontext") )
Christophe Palmann's avatar
Christophe Palmann committed
221
      m_Filter->ImportContext(GetParameterString("incontext"));
Christophe Palmann's avatar
Christophe Palmann committed
222

223 224 225
    if ( IsParameterEnabled("outcontext") )
      m_Filter->ExportContext(GetParameterString("outcontext"));

Christophe Palmann's avatar
Christophe Palmann committed
226 227
    // Set the output image
    SetParameterOutputImage("out", m_Filter->GetOutput());
228

229

Christophe Palmann's avatar
Christophe Palmann committed
230 231 232 233 234 235 236 237 238 239 240
  }

  BandMathImageFilterType::Pointer  m_Filter;
};

} // namespace Wrapper
} // namespace otb

OTB_APPLICATION_EXPORT(otb::Wrapper::BandMathX)