<commit_before>\chapter{The {\tt stereo.default} File}
\label{ch:stereodefault}

The \texttt{stereo.default} file contains configuration parameters
that the \texttt{stereo} program uses to process images.  The
\texttt{stereo.default} file is loaded from the current working
directory when you run \texttt{stereo} unless you specify a different
file using the \texttt{-s} option. Run \texttt{stereo -\/-help} for
more information. The extension is not important for this file.

A sample \texttt{stereo.default.example} file is included in the
\texttt{examples/} directory of the Stereo Pipeline software
distribution.

As mentioned in section \ref{cmdline}, all the \texttt{stereo}
parameters can also be specified on the command line.

Listed below are the parameters used by \texttt{stereo}, grouped by
processing stage.


% -------------------------------------------------------------------
%                           PREPROCESSING
% -------------------------------------------------------------------

\section{Preprocessing}
\label{stereo-default-preprocessing}
\hrule
\bigskip

\begin{description}

\item[alignment-method \textnormal{\small{(= affineepipolar, homography,
      epipolar, none)}} (default = affineepipolar)] \hfill \\

  When \texttt{alignment-method} is set to \texttt{homography},
  \texttt{stereo} will attempt to pre-align the images by
  automatically detecting tie-points between images using a feature
  based image matching technique. Tie points are stored in a
  \texttt{*.match} file that is used to compute a linear homography
  transformation of the right image so that it closely matches the
  left image.  Note: the user may exercise more control over this
  process by using the \texttt{ipfind} and \texttt{ipmatch} tools.

  When \texttt{alignment-method} is set to \texttt{affineepipolar},
  \texttt{stereo} will attempt to pre-align the images by detecting
  tie-points, as earlier, and using those to transform the images such
  that pairs of conjugate epipolar lines become collinear and parallel to
  one of the image axes.  The effect of this is equivalent to rotating the
  original cameras which took the pictures.

  When \texttt{alignment-method} is set to \texttt{epipolar},
  \texttt{stereo} will apply a 3D transform to both images so that
  their epipolar lines will be horizontal. This speeds of stereo
  correlation as it greatly reduces the area required for searching.

  {\em Epipolar alignment is only available when performing stereo
    matches using the pinhole stereo session (i.e. when using}
  \texttt{stereo -t pinhole}){\em, and cannot be used when processing
    ISIS images at this time.}

\item[left-image-crop-win \textnormal xoff yoff xsize ysize] \hfill \\
Do stereo in a sub-region of the left image [default: use the entire image].

\item[right-image-crop-win \textnormal xoff yoff xsize ysize] \hfill \\
When combined with \texttt{left-image-crop-win}, do stereo in given subregions
of left and right images. The crop windows can be determined using \texttt{stereo\_gui}.
It is important to note that when both of these
are specified, we explicitly crop the input images to these regions,
which does not happen when \texttt{left-image-crop-win} alone is specified.
In that case we use the full images but only restrict the computation
to the specified region. 

\item[force-use-entire-range \textnormal (default = false)] \hfill \\
  By default, the Stereo Pipeline will normalize ISIS images so that
  their maximum and minimum channel values are $\pm$2 standard
  deviations from a mean value of 1.0.  Use this option if you want to
  {\em disable} normalization and force the raw
  values to pass directly to the stereo correlations algorithms.

  For example, if ISIS's \texttt{histeq} has already been used to
  normalize the images, then use this option to disable normalization
  as a (redundant) pre-processing step.


\item[individually-normalize \textnormal (default = false)] \hfill \\
  By default, the maximum and minimum valid pixel value is determined
  by looking at both images.  Normalized with the same ``global'' min
  and max guarantees that the two images will retain their brightness
  and contrast relative to each other.

  This option forces each image to be normalized to its own maximum
  and minimum valid pixel value. This is useful in the event that
  images have different and non-overlapping dynamic ranges. You can
  sometimes tell when this option is needed: after a failed stereo
  attempt one of the rectified images (\texttt{*-L.tif} and
  \texttt{*-R.tif}) may be either mostly white or black.  Activating
  this option may correct this problem.

  Note: Photometric calibration and image normalization are steps that
  can and should be carried out beforehand using ISIS's own utilities.
  This provides the best possible input to the stereo pipeline and
  yields the best stereo matching results.

\item[ip-per-tile]  \hfill \\
How many interest points to detect in each $1024^2$ image tile (default: automatic
determination).

\item[ip-detect-method]  \hfill \\
What type of interest point detection algorithm to use for image alignment.
0 = Custom OBAloG implementation (default)
1 = SIFT implementation from OpenCV
2 = ORB implementation from OpenCV
If the default method does not perform well, try out one of the other two methods.

\item[epipolar-threshold]  \hfill \\
Maximum distance in pixels from the epipolar line to search for matches for each
interest point.  Due to the way ASP finds matches, reducing this value can actually
increase the number of interest points detected.  If image alignment seems to be working
well but you are not getting enough interest points to get a good search range estimate,
try setting this value to a small number, perhaps in the low double digits.

\item[ip-inlier-factor \textnormal (default = 1.0/15)] \hfill \\ A
higher factor will result in more interest points, but perhaps also
more outliers.  It is important to note that this parameter overlaps
somewhat in scope and effect with \texttt{epipolar-threshold} and
sometimes not both are active. It is suggested to experiement with both,
as well as with \texttt{ip-uniqueness-threshold} below, which has a
different justification but also somewhat similar effects.
 
\item[ip-uniqueness-threshold \textnormal (default = 0.7)] \hfill \\
A higher threshold will result in more interest points, but perhaps less unique ones.

\texttt{-\/-ip-triangulation-max-error \textit{double}} &
When matching IP, filter out any pairs with a triangulation error higher than this.
\\ \hline
<commit_msg>Doc fix<commit_after>\chapter{The {\tt stereo.default} File}
\label{ch:stereodefault}

The \texttt{stereo.default} file contains configuration parameters
that the \texttt{stereo} program uses to process images.  The
\texttt{stereo.default} file is loaded from the current working
directory when you run \texttt{stereo} unless you specify a different
file using the \texttt{-s} option. Run \texttt{stereo -\/-help} for
more information. The extension is not important for this file.

A sample \texttt{stereo.default.example} file is included in the
\texttt{examples/} directory of the Stereo Pipeline software
distribution.

As mentioned in section \ref{cmdline}, all the \texttt{stereo}
parameters can also be specified on the command line.

Listed below are the parameters used by \texttt{stereo}, grouped by
processing stage.


% -------------------------------------------------------------------
%                           PREPROCESSING
% -------------------------------------------------------------------

\section{Preprocessing}
\label{stereo-default-preprocessing}
\hrule
\bigskip

\begin{description}

\item[alignment-method \textnormal{\small{(= affineepipolar, homography,
      epipolar, none)}} (default = affineepipolar)] \hfill \\

  When \texttt{alignment-method} is set to \texttt{homography},
  \texttt{stereo} will attempt to pre-align the images by
  automatically detecting tie-points between images using a feature
  based image matching technique. Tie points are stored in a
  \texttt{*.match} file that is used to compute a linear homography
  transformation of the right image so that it closely matches the
  left image.  Note: the user may exercise more control over this
  process by using the \texttt{ipfind} and \texttt{ipmatch} tools.

  When \texttt{alignment-method} is set to \texttt{affineepipolar},
  \texttt{stereo} will attempt to pre-align the images by detecting
  tie-points, as earlier, and using those to transform the images such
  that pairs of conjugate epipolar lines become collinear and parallel to
  one of the image axes.  The effect of this is equivalent to rotating the
  original cameras which took the pictures.

  When \texttt{alignment-method} is set to \texttt{epipolar},
  \texttt{stereo} will apply a 3D transform to both images so that
  their epipolar lines will be horizontal. This speeds of stereo
  correlation as it greatly reduces the area required for searching.

  {\em Epipolar alignment is only available when performing stereo
    matches using the pinhole stereo session (i.e. when using}
  \texttt{stereo -t pinhole}){\em, and cannot be used when processing
    ISIS images at this time.}

\item[left-image-crop-win \textnormal xoff yoff xsize ysize] \hfill \\
Do stereo in a sub-region of the left image [default: use the entire image].

\item[right-image-crop-win \textnormal xoff yoff xsize ysize] \hfill \\
When combined with \texttt{left-image-crop-win}, do stereo in given subregions
of left and right images. The crop windows can be determined using \texttt{stereo\_gui}.
It is important to note that when both of these
are specified, we explicitly crop the input images to these regions,
which does not happen when \texttt{left-image-crop-win} alone is specified.
In that case we use the full images but only restrict the computation
to the specified region. 

\item[force-use-entire-range \textnormal (default = false)] \hfill \\
  By default, the Stereo Pipeline will normalize ISIS images so that
  their maximum and minimum channel values are $\pm$2 standard
  deviations from a mean value of 1.0.  Use this option if you want to
  {\em disable} normalization and force the raw
  values to pass directly to the stereo correlations algorithms.

  For example, if ISIS's \texttt{histeq} has already been used to
  normalize the images, then use this option to disable normalization
  as a (redundant) pre-processing step.


\item[individually-normalize \textnormal (default = false)] \hfill \\
  By default, the maximum and minimum valid pixel value is determined
  by looking at both images.  Normalized with the same ``global'' min
  and max guarantees that the two images will retain their brightness
  and contrast relative to each other.

  This option forces each image to be normalized to its own maximum
  and minimum valid pixel value. This is useful in the event that
  images have different and non-overlapping dynamic ranges. You can
  sometimes tell when this option is needed: after a failed stereo
  attempt one of the rectified images (\texttt{*-L.tif} and
  \texttt{*-R.tif}) may be either mostly white or black.  Activating
  this option may correct this problem.

  Note: Photometric calibration and image normalization are steps that
  can and should be carried out beforehand using ISIS's own utilities.
  This provides the best possible input to the stereo pipeline and
  yields the best stereo matching results.

\item[ip-per-tile]  \hfill \\
How many interest points to detect in each $1024^2$ image tile (default: automatic
determination).

\item[ip-detect-method]  \hfill \\
What type of interest point detection algorithm to use for image alignment.
0 = Custom OBAloG implementation (default)
1 = SIFT implementation from OpenCV
2 = ORB implementation from OpenCV
If the default method does not perform well, try out one of the other two methods.

\item[epipolar-threshold]  \hfill \\
Maximum distance in pixels from the epipolar line to search for matches for each
interest point.  Due to the way ASP finds matches, reducing this value can actually
increase the number of interest points detected.  If image alignment seems to be working
well but you are not getting enough interest points to get a good search range estimate,
try setting this value to a small number, perhaps in the low double digits.

\item[ip-inlier-factor \textnormal (default = 1.0/15)] \hfill \\ A
higher factor will result in more interest points, but perhaps also
more outliers.  It is important to note that this parameter overlaps
somewhat in scope and effect with \texttt{epipolar-threshold} and
sometimes not both are active. It is suggested to experiement with both,
as well as with \texttt{ip-uniqueness-threshold} below, which has a
different justification but also somewhat similar effects.
 
\item[ip-uniqueness-threshold \textnormal (default = 0.7)] \hfill \\
A higher threshold will result in more interest points, but perhaps less unique ones.

\texttt{-\/-ip-triangulation-max-error \textit{double}} \hfill \\
When matching IP, filter out any pairs with a triangulation error higher than this.

{'fraction_non_alphanumeric': 0.08205788755872102, 'fraction_numerical': 0.0027276860130322775, 'mean_word_length': 3.672212389380531, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5080024', 'n_tokens_mistral': 3539, 'n_tokens_neox': 3310, 'n_words': 1753}