.. _sfs:
sfs
---
The ``sfs`` tool can add more detail to a DEM using shape-from-shading
(:cite:`alexandrov2018multiview`). The ``parallel_sfs`` program
(:numref:`parallel_sfs`) extends ``sfs`` to run using multiple
processes on multiple machines.
Illustration
~~~~~~~~~~~~
.. figure:: ../images/SfS_Comet_67P.png
:name: SfS_Comet_67P
:alt: SfS_Comet_67P.png
Refining the surface of Comet 67P with shape-from-shading
(:cite:`jindal2024measuring_v2`). Left: produced terrain. Right: input image.
Other examples are in :numref:`sfs_usage` (for LRO NAC images), and in
:numref:`sfs_kaguya` (for Kaguya Terrain Camera images).
Usage
~~~~~
::
sfs -i -n -o \
[other options]
The tool outputs at each iteration the current DEM and other auxiliary
and appropriately-named datasets, which are documented further down.
Example
~~~~~~~
::
sfs --max-iterations 5 --use-approx-camera-models \
--crop-input-images --bundle-adjust-prefix ba/run \
-i input_dem.tif image1.cub image2.cub -o run/run
See many detailed worked-out examples for LRO NAC in :numref:`sfs_usage`,
and an example for the Kaguya Terrain Camera in :numref:`sfs_kaguya`.
Inputs
~~~~~~
The SfS program takes as input a DEM to refine, images, cameras
(contained within the ``.cub`` image files for ISIS data), Sun positions
(normally embedded in the cameras), and (optionally but strongly
suggested) camera adjustments, which makes sure the images are
registered to each other and to the ground (the detailed examples in
:numref:`sfs_usage` discuss this).
.. _sfs_outputs:
Outputs
~~~~~~~
The ``sfs`` outputs are saved at the location given by the output prefix (option
``-o``). If that is set to ``run/run`` as in the example above, the
outputs are:
- ``run/run-DEM-final.tif`` - The refined SfS DEM.
- ``run/run-comp-albedo-final.tif`` - The computed albedo. All its values are 1 unless
the option ``--float-albedo`` is used.
- ``run/run-exposures.txt`` - computed exposures for the images. These can be passed
back to ``sfs`` via ``--image-exposures-prefix``.
- ``run/run--final-meas-intensity.tif`` - For each input image, this
has the actual (measured) image values at each refined DEM grid point.
- ``run/run--final-comp-intensity.tif`` - For each input image,
this has the simulated image values at each refined DEM grid point using
the reflectance model and the Sun position for the
current image. If the modeling is perfect, the measured input image
will precisely agree with the simulated (modeled) image. In reality
these are close but different.
- ``run/run--final-meas-albedo.tif`` - This stores the measured
input image divided by the exposure times computed reflectance. Hence
this is more of an input quantity rather than the result of computing
the albedo. That one is mentioned above.
In addition, SfS saves intermediate values of many of these quantities
at each iteration, unless the flag ``--save-sparingly`` is used. SfS
may also save the "haze" values if this is solved for (see the
appropriate options below).
Command-line options for sfs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-i, --input-dem
The input DEM to refine using SfS.
--image-list
A file containing the list of images, when they are too many to
specify on the command line. Use space or newline as
separator. See also ``--camera-list``.
--camera-list
A file containing the list of cameras, when they are too many to
specify on the command line. If the images have embedded camera
information, such as for ISIS, this file must be empty but must
be specified if ``--image-list`` is specified.
-o, --output-prefix
Prefix for output filenames.
-n, --max-iterations
Set the maximum number of iterations. Normally 5-10 iterations is
enough, even when convergence is not reached, as the solution
usually improves quickly at first and only very fine refinements
happen later.
--reflectance-type
Reflectance types:
0. Lambertian
1. Lunar-Lambert
2. Hapke
3. Experimental extension of Lunar-Lambert
4. Charon model (a variation of Lunar-Lambert).
--smoothness-weight
The weight given to the cost function term which consists of sums
of squares of second-order derivatives. A larger value will result
in a smoother solution with fewer artifacts. See also
``--gradient-weight``.
--initial-dem-constraint-weight
A larger value will try harder to keep the SfS-optimized DEM
closer to the initial guess DEM. A value between 0.0001 and
0.001 may work, unless your initial DEM is very unreliable.
--albedo-constraint-weight
If floating the albedo, a larger value will try harder to keep
the optimized albedo close to the nominal value of 1. See also
``--albedo-robust-threshold``.
--albedo-robust-threshold
If floating the albedo and this threshold is positive, apply a Cauchy loss
with this threshold to the product of the albedo difference and the albedo
constraint weight.
--bundle-adjust-prefix
Use the camera adjustments obtained by previously running
bundle_adjust with this output prefix.
--float-albedo
Float the albedo for each pixel. Will give incorrect results
if only one image is present. The albedo is normalized, its
nominal value is 1.
--float-exposure
Float the exposure for each image. Will give incorrect results
if only one image is present. It usually gives marginal results.
--float-cameras
Float the camera pose for each image except the first one. It is
suggested that this option be avoided and bundle adjustment
be used instead.
--float-all-cameras
Float the camera pose for each image, including the first
one. Experimental. It is suggested to avoid this option.
--shadow-thresholds
Optional shadow thresholds for the input images (a list of real
values in quotes, one per image).
--shadow-threshold
A shadow threshold to apply to all images instead of using
individual thresholds. (Must be positive.)
--custom-shadow-threshold-list
A list having one image and one shadow threshold per line. For the
images specified there, override the shadow threshold supplied by
other means with this value.
--robust-threshold
If positive, set the threshold for the robust
measured-to-simulated intensity difference (using the Cauchy
loss). Any difference much larger than this will be penalized.
A good value may be 5% to 25% of the average image value or the
same fraction of the computed image exposure values.
--estimate-height-errors
Estimate the SfS DEM height uncertainty (in meters) by finding the height
perturbation at each grid point which will make at least one of the
simulated images at that point change by more than twice the discrepancy
between the unperturbed simulated image and the measured image. The SfS DEM
must be provided via the -i option. The number of iterations, blending
parameters (``--blending-dist``, etc.), and smoothness weight are ignored.
Results are not computed at image pixels in shadow. This produces -height-error.tif``. No SfS DEM is computed. This uncertainty may
be somewhat optimistic (:cite:`jindal2024measuring_v2`).
--height-error-params
Specify the largest height deviation to examine (in meters), and
how many samples to use from 0 to that height.
--model-shadows
Model the fact that some points on the DEM are in the shadow
(occluded from the Sun).
--sun-positions
A file having on each line an image name and three values in
double precision specifying the Sun position in meters in
ECEF coordinates (origin is planet center). Use a space as
separator. If not provided, these will be read from
the camera file for ISIS and CSM models.
--save-dem-with-nodata
Save a copy of the DEM while using a no-data value at a DEM
grid point where all images show shadows. To be used if shadow
thresholds are set.
--use-approx-camera-models
Use approximate camera models for speed. Only with ISIS .cub
cameras.
--use-rpc-approximation
Use RPC approximations for the camera models instead of approximate
tabulated camera models (invoke with ``--use-approx-camera-models``).
This is broken and should not be used.
--rpc-penalty-weight
The RPC penalty weight to use to keep the higher-order RPC
coefficients small, if the RPC model approximation is used.
Higher penalty weight results in smaller such coefficients.
--coarse-levels
Solve the problem on a grid coarser than the original by a
factor of 2 to this power, then refine the solution on finer
grids. Experimental. It is suggested to not use this option.
--max-coarse-iterations
How many iterations to do at levels of resolution coarser than
the final result.
--crop-input-images
Crop the images to a region that was computed to be large enough
and keep them fully in memory, for speed.
--blending-dist
Give less weight to image pixels close to no-data or boundary
values. Enabled only when crop-input-images is true, for
performance reasons. Blend over this many pixels. See also
``--blending-power``, ``--min-blend-size`` and
``--allow-borderline-data``. See example in :numref:`sfs-lola`.
--blending-power
Raise the blending weights (they are no more to 1.0) to this
power. A higher value will result in smoother (but more abrupt)
blending as the weights decay faster close to 0.
--min-blend-size
Do not apply blending in shadowed areas of dimensions less than
this. This avoids losing data around small holes, but the solution
may become less smooth.
--compute-exposures-only
Quit after saving the exposures. This should be done once for
a big DEM, before using these for small sub-clips without
recomputing them.
--image-exposures-prefix
Use this prefix to optionally read initial exposures (filename
is ``-exposures.txt``).
--save-computed-intensity-only
Save the computed (simulated) image intensities for given DEM,
images, cameras, and reflectance model, without refining the
DEM. The exposures will be computed along the way unless specified
via ``--image-exposures-prefix``, and saved to
-exposures.txt.
--allow-borderline-data
At the border of the region where there are no lit pixels in any
images, do not let the blending weights decay to 0. This
noticeably improves the level of detail. The
``sfs_blend`` (:numref:`sfs_blend`) tool may need to be
used to further tune this region. See an
illustration in :numref:`sfs_borderline`.
--model-coeffs-prefix
Use this prefix to optionally read model coefficients from a
file (filename is ``-model_coeffs.txt``).
--model-coeffs
Use the model coefficients specified as a list of numbers in
quotes. For example:
* Lunar-Lambertian: O, A, B, C, would be ``"1 -0.019 0.000242 -0.00000146"``
* Hapke: omega, b, c, B0, h, would be ``"0.68 0.17 0.62 0.52 0.52"``
* Charon: A, f(alpha), would be ``"0.7 0.63"``
--crop-win
Crop the input DEM to this region before continuing.
--init-dem-height
Use this value for initial DEM heights (measured in meters, relative to the
datum). An input DEM still needs to be provided for georeference
information.
--nodata-value
Use this as the DEM no-data value, over-riding what is in the
initial guess DEM.
--float-dem-at-boundary
Allow the DEM values at the boundary of the region to also float
(not advised).
--fix-dem
Do not float the DEM at all. Useful when floating the model params.
--float-reflectance-model
Allow the coefficients of the reflectance model to float (not
recommended).
--query
Print some info, including DEM size and the solar azimuth and
elevation for the images, and exit. Invoked from parallel_sfs.
-t, --session-type
Select the stereo session type to use for processing. Usually
the program can select this automatically by the file extension,
except for xml cameras. See :numref:`ps_options` for
options.
--steepness-factor
Try to make the terrain steeper by this factor. This is not
recommended in regular use.
--curvature-in-shadow
Attempt to make the curvature of the DEM (the Laplacian) at
points in shadow in all images equal to this value, which should
make the DEM curve down.
--curvature-in-shadow-weight
The weight to give to the curvature in shadow constraint.
--lit-curvature-dist
If using a curvature in shadow, start phasing it in this far from
the shadow boundary in the lit region (in units of pixels).
--shadow-curvature-dist
If using a curvature in shadow, have it fully phased in this far
from shadow boundary in the shadow region (in units of pixels).
--integrability-constraint-weight
Use the integrability constraint from Horn 1990 with this value
of its weight (experimental).
--smoothness-weight-pq
Smoothness weight for p and q, when the integrability constraint
is used. A larger value will result in a smoother solution
(experimental).
--num-haze-coeffs
Set this to 1 to model the problem as ``image = exposure * albedo *
reflectance + haze``, where ``haze`` is a single value for each
image. This models a small quantity of stray light entering the lens
due to scattering and other effects. Use ``--float-haze`` to actually
optimize the haze (it starts as 0). It will be written as ``-haze.txt``
(ignore all columns of numbers in that file except the first one).
--float-haze
If specified, float the haze coefficients as part of the
optimization, if haze is modeled, so if ``--num-haze-coeffs`` is 1.
--haze-prefix
Use this prefix to read initial haze values (filename is
``-haze.txt``). The file format is the same as what the
tool writes itself, when triggered by the earlier options. If haze is
modeled, it will be initially set to 0 unless read from such a
file, and will be floated or not depending on whether ``--float-haze``
is on. The final haze values will be saved to ``-haze.txt``.
--gradient-weight
The weight given to the cost function term which consists of sums
of squares of first-order derivatives. A larger value will result
in shallower slopes but less noise. This can be used in conjunction with
``--smoothness-weight``. It is suggested to experiment with this
with a value of 0.0001 - 0.01, while reducing the
smoothness weight to a very small value.
--save-sparingly
Avoid saving any results except the adjustments and the DEM, as
that's a lot of files.
--camera-position-step-size
Larger step size will result in more aggressiveness in varying
the camera position if it is being floated (which may result
in a better solution or in divergence).
--threads
How many threads each process should use. This will be changed to
1 for ISIS cameras when ``--use-approx-camera-models`` is not set,
as ISIS is single-threaded. Not all parts of the computation
benefit from parallelization.
--cache-size-mb
Set the system cache size, in MB.
--tile-size
Image tile size used for multi-threaded processing.
--no-bigtiff
Tell GDAL to not create bigtiffs.
--tif-compress
TIFF compression method.
-v, --version
Display the version of software.
-h, --help
Display this help message.