Commit d3bf43a8 authored by Victor Poughon's avatar Victor Poughon
Browse files

DOC: Move extended filename section from SoftwareGuide to CookBook

parent 57941e97
......@@ -468,3 +468,278 @@ among 560 cpus and took only 56 seconds.
Note that this MPI parallel invocation of applications is only
available for command-line calls to OTB applications, and only for
images output parameters.
Extended filename for reader and writer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Purpose
^^^^^^^
There are multiple ways to define geo-referencing information. For
instance, one can use a geographic transform, a cartographic projection,
or a sensor model with RPC coefficients. A single image may contain
several of these elements, such as in the “ortho-ready” products : this
is a type of product still in sensor geometry (the sensor model is
supplied with the image) but it also contains an approximative
geographic transform that can be used to have a quick estimate of the
image localisation. For instance, your product may contain a “.TIF” file
for the image, along with a “.RPB” file that contains the sensor model
coefficients and an “.IMD” file that contains a cartographic projection.
This case leads to the following question : which geo-referencing
element should be used when opening this image in an OTB reader. In
fact, it depends on the users need. For an orthorectification
application, the sensor model must be used. In order to specify which
information should be skipped, a syntax of extended filenames has been
developed for both reader and writer.
Syntax
^^^^^^
The reader and writer extended file name support is based on the same
syntax, only the options are different. To benefit from the extended
file name mechanism, the following syntax is to be used:
::
Path/Image.ext?&key1=<value1>&key2=<value2>
IMPORTANT: Note that you’ll probably need to “quote” the filename.
Reader options
^^^^^^^^^^^^^^
**Available Options:**
- ::
&geom=<path/filename.geom>
- Contains the file name of a valid geom file
- Use the content of the specified geom file instead of
image-embedded geometric information
- empty by default, use the image-embedded information if available
- ::
&sdataidx=<(int)idx>
- Select the sub-dataset to read
- 0 by default
- ::
&resol=<(int)resolution factor>
- Select the JPEG2000 sub-resolution image to read
- 0 by default
- ::
&bands=r1,r2,...,rn
- Select a subset of bands from the input image
- The syntax is inspired by Python indexing syntax with
bands=r1,r2,r3,...,rn where each ri is a band range that can be :
- a single index (1-based) :
- :math:`'2'` means 2nd band
- :math:`'-1'` means last band
- or a range of bands :
- :math:`'3:'` means 3rd band until the last one
- :math:`':-2'` means the first bands until the second to last
- :math:`'2:4'` means bands 2,3 and 4
- empty by default (all bands are read from the input image)
- ::
&skipcarto=<(bool)true>
- Skip the cartographic information
- Clears the projectionref, set the origin to :math:`[0,0]` and the
spacing to
:math:`[1/max(1,resolution factor),1/max(1,resolution factor)]`
- Keeps the keyword list
- false by default
- ::
&skipgeom=<(bool)true>
- Skip geometric information
- Clears the keyword list
- Keeps the projectionref and the origin/spacing information
- false by default.
- ::
&skiprpctag=<(bool)true>
- Skip the reading of internal RPC tags (see
[sec:TypesofSensorModels] for details)
- false by default.
Writer options
^^^^^^^^^^^^^^
**Available Options:**
- ::
&writegeom=<(bool)false>
- To activate writing of external geom file
- true by default
- ::
&writerpctags=<(bool)true>
- To activate writing of RPC tags in TIFF files
- false by default
- ::
&gdal:co:<GDALKEY>=<VALUE>
- To specify a gdal creation option
- For gdal creation option information, see dedicated gdal
documentation
- None by default
- ::
&streaming:type=<VALUE>
- Activates configuration of streaming through extended filenames
- Override any previous configuration of streaming
- Allows to configure the kind of streaming to perform
- Available values are:
- auto : tiled or stripped streaming mode chosen automatically
depending on TileHint read from input files
- tiled : tiled streaming mode
- stripped : stripped streaming mode
- none : explicitly deactivate streaming
- Not set by default
- ::
&streaming:sizemode=<VALUE>
- Allows to choose how the size of the streaming pieces is computed
- Available values are:
- auto : size is estimated from the available memory setting by
evaluating pipeline memory print
- height : size is set by setting height of strips or tiles
- nbsplits : size is computed from a given number of splits
- Default is auto
- ::
&streaming:sizevalue=<VALUE>
- Parameter for size of streaming pieces computation
- Value is :
- if sizemode=auto : available memory in Mb
- if sizemode=height : height of the strip or tile in pixels
- if sizemode=nbsplits : number of requested splits for streaming
- If not provided, the default value is set to 0 and result in
different behaviour depending on sizemode (if set to height or
nbsplits, streaming is deactivated, if set to auto, value is
fetched from configuration or cmake configuration file)
- ::
&box=<startx>:<starty>:<sizex>:<sizey>
- User defined parameters of output image region
- The region must be set with 4 unsigned integers (the separator
used is the colon ’:’). Values are:
- startx: first index on X (starting with 0)
- starty: first index on Y (starting with 0)
- sizex: size along X
- sizey: size along Y
- The definition of the region follows the same convention as
itk::Region definition in C++. A region is defined by two classes:
the itk::Index and itk::Size classes. The origin of the region
within the image with which it is associated is defined by Index
- ::
&bands=r1,r2,...,rn
- Select a subset of bands from the output image
- The syntax is inspired by Python indexing syntax with
bands=r1,r2,r3,...,rn where each ri is a band range that can be :
- a single index (1-based) :
- :math:`'2'` means 2nd band
- :math:`'-1'` means last band
- or a range of bands :
- :math:`'3:'` means 3rd band until the last one
- :math:`':-2'` means the first bands until the second to last
- :math:`'2:4'` means bands 2,3 and 4
- empty by default (all bands are write from the output image)
The available syntax for boolean options are:
- ON, On, on, true, True, 1 are available for setting a ’true’ boolean
value
- OFF, Off, off, false, False, 0 are available for setting a ’false’
boolean value
......@@ -193,238 +193,3 @@ images is the processing of SLC SAR images, which are complex.
\label{sec:ReadingImageSeries}
\input{ImageSeriesIOExample}
\section{Extended filename for reader and writer}
\label{sec:ExtendedFilename}
\subsection{Purpose}
There are multiple ways to define geo-referencing information. For instance,
one can use a geographic transform, a cartographic projection, or a sensor
model with RPC coefficients. A single image may contain several of these
elements, such as in the "ortho-ready" products : this is a type of product
still in sensor geometry (the sensor model is supplied with the image)
but it also contains an approximative geographic transform that can be used
to have a quick estimate of the image localisation. For instance, your product
may contain a ".TIF" file for the image, along with a ".RPB" file that contains
the sensor model coefficients and an ".IMD" file that contains a cartographic
projection.
This case leads to the following question : which geo-referencing element
should be used when opening this image in an OTB reader. In fact, it depends on
the users need. For an orthorectification application, the sensor model must be
used. In order to specify which information should be skipped, a syntax of
extended filenames has been developed for both reader and writer.
\subsection{Syntax}
The reader and writer extended file name support is based on the same syntax,
only the options are different. To benefit from the extended file name
mechanism, the following syntax is to be used:
\begin{verbatim}
Path/Image.ext?&key1=<value1>&key2=<value2>
\end{verbatim}
IMPORTANT: Note that you'll probably need to "quote" the filename.
\subsection{Reader options}
\textbf{Available Options:}
\begin{itemize}
\item \begin{verbatim}&geom=<path/filename.geom>\end{verbatim}
\begin{itemize}
\item Contains the file name of a valid geom file
\item Use the content of the specified geom file instead of image-embedded
geometric information
\item empty by default, use the image-embedded information if available
\end{itemize}
\item \begin{verbatim}&sdataidx=<(int)idx>\end{verbatim}
\begin{itemize}
\item Select the sub-dataset to read
\item 0 by default
\end{itemize}
\item \begin{verbatim}&resol=<(int)resolution factor>\end{verbatim}
\begin{itemize}
\item Select the JPEG2000 sub-resolution image to read
\item 0 by default
\end{itemize}
\item \begin{verbatim}&bands=r1,r2,...,rn\end{verbatim}
\begin{itemize}
\item Select a subset of bands from the input image
\item The syntax is inspired by Python indexing syntax with
bands=r1,r2,r3,...,rn where each ri is a band range that can be :
\begin{itemize}
\item a single index (1-based) :
\begin{itemize}
\item $'2'$ means 2nd band
\item $'-1'$ means last band
\end{itemize}
\item or a range of bands :
\begin{itemize}
\item $'3:'$ means 3rd band until the last one
\item $':-2'$ means the first bands until the second to last
\item $'2:4'$ means bands 2,3 and 4
\end{itemize}
\end{itemize}
\item empty by default (all bands are read from the input image)
\end{itemize}
\item \begin{verbatim}&skipcarto=<(bool)true>\end{verbatim}
\begin{itemize}
\item Skip the cartographic information
\item Clears the projectionref, set the origin to $[0,0]$ and the spacing to $[1/max(1,resolution factor),1/max(1,resolution factor)]$
\item Keeps the keyword list
\item false by default
\end{itemize}
\item \begin{verbatim}&skipgeom=<(bool)true>\end{verbatim}
\begin{itemize}
\item Skip geometric information
\item Clears the keyword list
\item Keeps the projectionref and the origin/spacing information
\item false by default.
\end{itemize}
\item \begin{verbatim}&skiprpctag=<(bool)true>\end{verbatim}
\begin{itemize}
\item Skip the reading of internal RPC tags (see \ref{sec:TypesofSensorModels} for details)
\item false by default.
\end{itemize}
\end{itemize}
\subsection{Writer options}
\textbf{Available Options:}
\begin{itemize}
\item \begin{verbatim}&writegeom=<(bool)false>\end{verbatim}
\begin{itemize}
\item To activate writing of external geom file
\item true by default
\end{itemize}
\item \begin{verbatim}&writerpctags=<(bool)true>\end{verbatim}
\begin{itemize}
\item To activate writing of RPC tags in TIFF files
\item false by default
\end{itemize}
\item \begin{verbatim}&gdal:co:<GDALKEY>=<VALUE>\end{verbatim}
\begin{itemize}
\item To specify a gdal creation option
\item For gdal creation option information, see dedicated gdal documentation
\item None by default
\end{itemize}
\item \begin{verbatim}&streaming:type=<VALUE>\end{verbatim}
\begin{itemize}
\item Activates configuration of streaming through extended filenames
\item Override any previous configuration of streaming
\item Allows to configure the kind of streaming to perform
\item Available values are:
\begin{itemize}
\item auto : tiled or stripped streaming mode chosen automatically depending on TileHint read from input files
\item tiled : tiled streaming mode
\item stripped : stripped streaming mode
\item none : explicitly deactivate streaming
\end{itemize}
\item Not set by default
\end{itemize}
\item \begin{verbatim}&streaming:sizemode=<VALUE>\end{verbatim}
\begin{itemize}
\item Allows to choose how the size of the streaming pieces is computed
\item Available values are:
\begin{itemize}
\item auto : size is estimated from the available memory setting by evaluating pipeline memory print
\item height : size is set by setting height of strips or tiles
\item nbsplits : size is computed from a given number of splits
\end{itemize}
\item Default is auto
\end{itemize}
\item \begin{verbatim}&streaming:sizevalue=<VALUE>\end{verbatim}
\begin{itemize}
\item Parameter for size of streaming pieces computation
\item Value is :
\begin{itemize}
\item if sizemode=auto : available memory in Mb
\item if sizemode=height : height of the strip or tile in pixels
\item if sizemode=nbsplits : number of requested splits for streaming
\end{itemize}
\item If not provided, the default value is set to 0 and result in different behaviour depending on sizemode (if set to height or nbsplits, streaming is deactivated, if set to auto, value is fetched from configuration or cmake configuration file)
\end{itemize}
\item \begin{verbatim}&box=<startx>:<starty>:<sizex>:<sizey>\end{verbatim}
\begin{itemize}
\item User defined parameters of output image region
\item The region must be set with 4 unsigned integers (the separator used is
the colon ':'). Values are:
\begin{itemize}
\item startx: first index on X (starting with 0)
\item starty: first index on Y (starting with 0)
\item sizex: size along X
\item sizey: size along Y
\end{itemize}
\item The definition of the region follows the same convention as itk::Region
definition in C++. A region is defined by two classes: the itk::Index and
itk::Size classes. The origin of the region within the image with which it
is associated is defined by Index
\end{itemize}
\item \begin{verbatim}&bands=r1,r2,...,rn\end{verbatim}
\begin{itemize}
\item Select a subset of bands from the output image
\item The syntax is inspired by Python indexing syntax with
bands=r1,r2,r3,...,rn where each ri is a band range that can be :
\begin{itemize}
\item a single index (1-based) :
\begin{itemize}
\item $'2'$ means 2nd band
\item $'-1'$ means last band
\end{itemize}
\item or a range of bands :
\begin{itemize}
\item $'3:'$ means 3rd band until the last one
\item $':-2'$ means the first bands until the second to last
\item $'2:4'$ means bands 2,3 and 4
\end{itemize}
\end{itemize}
\item empty by default (all bands are write from the output image)
\end{itemize}
\end{itemize}
The available syntax for boolean options are:
\begin{itemize}
\item ON, On, on, true, True, 1 are available for setting a 'true' boolean value
\item OFF, Off, off, false, False, 0 are available for setting a 'false' boolean value
\end{itemize}
%% \section{Reading and Writing Image Series}
%% It is still quite common to store 3D medical images in sets of files each one
%% containing a single slice of a volume dataset. Those 2D files can be read as
%% individual 2D images, or can be grouped together in order to reconstruct a 3D
%% dataset. The same practice can be extended to higher dimensions, for example,
%% for managing 4D datasets by using sets of files each one containing a 3D image.
%% This practice is common in the domain of cardiac imaging, perfusion, functional
%% MRI and PET. This section illustrates the functionalities available in ITK for
%% dealing with reading and writing series of images.
%% \index{Series!Reading}
%% \index{Series!Writing}
%% \index{Image Series!Reading}
%% \index{Image Series!Writing}
%% \subsection{Reading Image Series}
%% \label{sec:ReadingImageSeries}
%% \input{ImageSeriesReadWrite.tex}
%% \subsection{Writing Image Series}
%% \label{sec:WritingImageSeries}
%% %\input{ImageReadImageSeriesWrite.tex}
%% \subsection{Reading and Writing Series of RGB Images}
%% \label{sec:ReadingWritingRGBImageSeries}
%% %\input{RGBImageSeriesReadWrite.tex}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment