<commit_before>.. _image_align:

image_align
------------

The program ``image_align`` aligns a second image to a first image. In
the produced aligned second image, each feature has the same row and
column coordinates as in the first image.

Several alignment transforms are supported. The alignment transform is
determined with subpixel precision and is applied using bilinear
interpolation.

Features are matched among the images using either interest points
or a disparity produced with ASP's correlation algorithms.

If the first image is georeferenced, the second aligned image will use
the same georeference as the first one.  The first image and second
aligned image can then be blended with ``dem_mosaic``
(:numref:`dem_mosaic`).

The images are expected to have a single band and have float or
integer values. If the images have more than one band, only the first
one will be read. The processing is done in double precision. The
default output pixel value value is ``float32``, as casting to integer
may result in precision loss.

The alignment transform can be saved, and a custom alignment transform
can be applied instead of the one found automatically. The interest
point matches which determine the alignment transform can be saved as
well.

This tool extends the co-registration functionality of CASP-GO
(:numref:`casp_go`).

Examples
~~~~~~~~

::
   
    image_align image1.tif image2.tif -o image2_align.tif

Using a disparity produced from correlation::

    parallel_stereo --correlator-mode --stereo-algorithm asp_mgm \
      --subpixel-mode 2 image1.tif image2.tif run/run-corr

    image_align image1.tif image2.tif                            \
      --output-image image2_align.tif --output-prefix run/run    \
      --disparity-params "run/run-corr-F.tif 1000000"

Note that ``--subpixel-mode 2`` will be quite slow but produce good
results. See :numref:`running-stereo` for the choices when it comes to
stereo algorithms and subpixel methods, and :numref:`correlator-mode`
for the image correlator functionality.

The disparity will be computed from the first to second image, but the
alignment transform is from the second to first image, so the disparity
and this transform will show opposite trends.

Application for alignment of DEMs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Given a DEM, it can be treated as an image with float values, or an
image can be produced from it with the ``hillshade`` command
(:numref:`hillshade`), or, if the DEM is obtained from a stereo point
cloud with ``point2dem``, an orthoimage in one-to-one correspondence
with this DEM can be created with the ``--orthoimage`` option of this
tool (:numref:`point2dem`).

In either case, given two DEMs, ``dem1.tif`` and ``dem2.tif``, their
corresponding images can be aligned to each other as::

    image_align image1.tif image2.tif --output-prefix run \
      --alignment-method translation -o image2_align.tif

Then, the alignment transform can be used to align the second DEM
to the first, as::

    image_align dem1.tif dem2.tif             \
      --input-transform run/run-transform.txt \
      -o dem2_align.tif 

It appears that applying this tool on the DEMs themselves may result
in more accurate results than if applied on their hillshaded images.
<commit_msg>image_align: Wording fixes<commit_after>.. _image_align:

image_align
------------

The program ``image_align`` aligns a second image to a first image. In
the produced aligned second image, each feature has the same row and
column coordinates as in the first image.

Several alignment transforms are supported. The alignment transform is
determined with subpixel precision and is applied using bilinear
interpolation.

Features are matched among the images using either interest points
or a disparity produced with ASP's correlation algorithms.

If the first image is georeferenced, the second aligned image will use
the same georeference as the first one.  The first image and second
aligned image can then be blended with ``dem_mosaic``
(:numref:`dem_mosaic`).

The images are expected to have a single band and have float or
integer values. If the images have more than one band, only the first
one will be read. The processing is done in double precision. The
default output pixel value value is ``float32``, as casting to integer
may result in precision loss.

The alignment transform can be saved, and a custom alignment transform
can be applied instead of the one found automatically. The interest
point matches which determine the alignment transform can be saved as
well.

This tool extends the co-registration functionality of CASP-GO
(:numref:`casp_go`).

Examples
~~~~~~~~

::
   
    image_align image1.tif image2.tif -o image2_align.tif

Using a disparity produced from correlation::

    parallel_stereo --correlator-mode --stereo-algorithm asp_mgm \
      --subpixel-mode 2 image1.tif image2.tif run/run-corr

    image_align image1.tif image2.tif                            \
      --output-image image2_align.tif --output-prefix run/run    \
      --disparity-params "run/run-corr-F.tif 1000000"

Note that ``--subpixel-mode 2`` will be quite slow but produce good
results. See :numref:`running-stereo` for the choices when it comes to
stereo algorithms and subpixel methods, and :numref:`correlator-mode`
for the image correlator functionality.

The disparity will be computed from the first to second image, but the
alignment transform is from the second to first image, so the disparity
and this transform will show opposite trends.

Application for alignment of DEMs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Given a DEM, it can be treated as an image with float values, or an
image can be produced from it with the ``hillshade`` command
(:numref:`hillshade`), or, if the DEM is obtained from a stereo point
cloud with ``point2dem``, an orthoimage in one-to-one correspondence
with this DEM can be created with the ``--orthoimage`` option of this
tool (:numref:`point2dem`).

In either case, given two DEMs, ``dem1.tif`` and ``dem2.tif``, their
corresponding images can be aligned to each other as::

    image_align image1.tif image2.tif --output-prefix run \
      --alignment-method translation -o image2_align.tif

Then, the alignment transform can be used to align the second DEM
to the first, as::

    image_align dem1.tif dem2.tif             \
      --input-transform run/run-transform.txt \
      -o dem2_align.tif 

It appears that applying this tool on the DEMs themselves may result
in more accurate results than if applied on their hillshaded images.
(Consider also using for hillshading the tool ``gdaldem hillshade``,
:numref:`gdal_tools`.)

{'fraction_non_alphanumeric': 0.07666817291760808, 'fraction_numerical': 0.008736255460159662, 'mean_word_length': 3.8609077598828696, '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': '4907595', 'n_tokens_mistral': 1852, 'n_tokens_neox': 1715, 'n_words': 880}