Using OTB Applications from GNU/Guile

otb-guile: using OTB applications from GNU/Guile

Jordi Inglada

July 18, 2013

Contents

1 Introduction1

2 Installation and conﬁguration2 2.1 Source code...... 2 2.2 Compile the shared library...... 2 2.3 Set up the environment variables...... 3

3 Using otb-guile4 3.1 The wrappers...... 4 3.2 Syntactic sugar for applications...... 5

4 Backlog6 4.1 Scheme...... 6 4.2 Wrappers...... 6 4.3 Doc...... 6

1 Introduction otb-guile is a package that allows to use the OTB applications wrapper API from GNU/Guile. Why another language wrapper for OTB applications when Python and Java are already available? Because languages matter. Or in detail:

1 Feature Java Python Guile Interpreted no yes yes Compiled yes no yes Functional no somewhat yes Parallel runtime yes no1 yes Support for macros no no yes Support for multiple languages2 yes no3 yes Cool NO! no yes

2 Installation and conﬁguration

2.1 Source code The source code is available on BitBucket and can be obtained using git: git clone https://[email protected]/inglada/otb-guile.git The source tree has this structure: README.org Scheme otb applications.scm cli-application.scm wrappers.scm Tests otb-tests.scm Wrappers CMakeLists.txt otb-applications.cxx

2.2 Compile the shared library 2.2.1 OTB is up and running

You will need a working installation of OTB with the application wrappers available. We assume that your PATH, LD_LIBRARY_PATH and ITK_AUTOLOAD_PATH are correctly set up and that you are able to use at least the command line OTB applications. 1See the interpreter lock for details. 2Is the virtual machine of the language able to use other languages? Java has Clojure, Scala, Groovy, etc. Guile suppports Javascript and Lua. 3Actually, there is Hy, but it does not seem mature enough yet.

2 2.2.2 Building the OTB Guile wrappers

The OTB Guile wrappers are just a shared library wrapping the calls to the OTB application wrappers API. As such, you just need to compile the library as an OTB project using CMake. We will assume that your otb-guile source tree is located in $HOME/local/src/otb-guile. We will deﬁne the following environment variables for convenience:

OTB_GUILE_DIR=$HOME/local/src/otb-guile OTB_GUILE_SCM=$OTB_GUILE_DIR/Scheme/ OTB_GUILE_BIN=$HOME/local/builds/otb-guile-bin

The compilation procedure is therefore: mkdir -p $OTB_GUILE_BIN cd $OTB_GUILE_BIN ccmake $OTB_GUILE_DIR/Wrappers

At this point we will use CMake as usual to conﬁgure and generate the build tree. And after that, we will run make whih will allow us to obtain the shared library libOTBApplicationEngineSCM.so located in $OTB_GUILE_BIN. I don’t usually run make install. If you choose to do that, you will have to update the $OTB_GUILE_BIN variable to the installation directory for the following steps.

2.3 Set up the environment variables In order to make the library and the wrappers available to Guile, you will need to update 2 environment variables. The ﬁrst one will make the shared library available for Guile: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$OTB_GUILE_BIN

And the second one will allow Guile to ﬁnd the scheme code which wraps the calls to the library: GUILE_LOAD_PATH=$GUILE_LOAD_PATH:$OTB_GUILE_SCM

And that should be all.

3 3 Using otb-guile

3.1 The wrappers If everything is correctly installed, you should be able to use the OTB applications API from the REPL:

Guile comes with ABSOLUTELY NO WARRANTY; for details type ‘,show w’. This program is free software, and you are welcome to redistribute it under certain conditions; type ‘,show c’ for details.

Enter ‘,help’ for help. scheme@(guile-user)> (use-modules (otb wrappers)) scheme@(guile-user)> (get-otb-application-list) $1 = ("BandMath" "BinaryMorphologicalOperation" "BlockMatching" "BundleToPerfectSensor" "ClassificationMapRegularization" "ColorMapping" "CompareImages" "ComputeConfusionMatrix" "ComputeImagesStatistics" "ComputePolylineFeatureFromImage" ..... "VectorDataTransform" "VertexComponentAnalysis")

The available functions are exported from $OTB_GUILE_SCM/otb/wrappers.scm. You can inspect this ﬁle to have the complete list. In order to use the API in your programs, you would do something like this:

(define-module(example applications) #:use-module((otb wrappers))) (get-otb-application-list)

And you can deﬁne functions to call the applications like this: (define*(band-math input-image-list output-image exp #:optional(pixel-type "float")) "Run the OTB BandMath application" (let((bm-app(make-otb-application "BandMath"))) (begin (set-otb-application-parameter-stringlist bm-app

4 "il" input-image-list) (set-otb-application-parameter-string bm-app "out" output-image) (set-otb-application-parameter-output-pixel-type bm-app pixel-type) (set-otb-application-parameter-string bm-app "exp" exp) (execute-otb-application bm-app) (clear-otb-application bm-app) output-image)))

Which allows you to do this:

(band-math ’("verySmallFSATSW_r.tif" "verySmallFSATSW_nir.tif" "verySmallFSATSW.tif") "apTvUtBandMathOutput.tif" "cos(im1b1)+im2b1*im3b1-im3b2+ndvi(im3b3, im3b4)")

Which is the equivalent of the following command line: otbcli_BandMath -il verySmallFSATSW_r.tif verySmallFSATSW_nir.tif\ verySmallFSATSW.tif -out apTvUtBandMathOutput.tif\ -exp "cos(im1b1)+im2b1*im3b1-im3b2+ndvi(im3b3, im3b4)"

3.2 Syntactic sugar for applications In order to make the use of the applications less tedious, some applications are already wrapped into scheme functions in $OTB_GUILE_SCM/otb/applications.scm. See the source code of the module to have the complete list. This module can be used like this in your programs:

(define-module(example band-math) #:use-module((otb applications)))

Of course, you can yourself in your programs create abstractions over these applications, as for instance:

(define(generate-validity-image-mask input-image-name output-image-name) "A pixel is not part of the validity-image if the first 3 bands are 0: (im1b1+im1b2+im1b3)==0"

5 (band-math(list input-image-name) output-image-name "(im1b1+im1b2+im1b3)!=0" "uint8"))

4 Backlog

4.1 Scheme 4.1.1 DONE Add proper testing using SRFI-41

• State "DONE" from "TODO" [2013-07-18 Thu 17:48]

4.1.2 TODO Enrich tests 4.1.3 TODO Add a test using guile parallel to demonstrate the bug with parallel execution 4.2 Wrappers 4.2.1 TODO Check that CMake guile detection is done properly 4.2.2 TODO Understand how the garbage collection for the smobs work 4.3 Doc 4.3.1 TODO Generate API documentation from sources