GRASS logo

NAME

p.photoclinometry - Photoclinometry: shape-from-shading DEM refinement.
Refines a seed DEM using a single calibrated reflectance image and a planetary photometric model (Hapke, Minnaert, LunarLambert, etc.). Implements the Horn-Brooks (1986) iterative gradient-domain shape-from-shading algorithm with numerical Jacobian evaluation. Phase angle is computed assuming nadir viewing geometry. Input reflectance must be calibrated (I/F or equivalent).

KEYWORDS

Planetary, Topography, photoclinometry, shape-from-shading, DEM

SYNOPSIS

p.photoclinometry
p.photoclinometry --help
p.photoclinometry input=name output=name [seed=name] albedo=float sunaz=float sunelev=float [model=string] [k=float] [l=float] [wh=float] [hh=float] [b0=float] [hg1=float] [hg2=float] [bh=float] [ch=float] [theta=float] [niter=integer] [lambda=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

input=name [required]
Calibrated reflectance raster (I/F)
Name of input raster map
output=name [required]
Output refined DEM raster
Name for output raster map
seed=name
Seed DEM raster (optional; flat if omitted)
Starting elevation field. Only low-frequency shape is needed; a coarse photometric or MOLA/LOLA DEM is ideal. If omitted, a flat (zero) surface is used.
albedo=float [required]
Surface normal albedo (dimensionless)
Apparent normal reflectance of the surface. For the Hapke model this is approximately wh*0.5*(1+b0); for Minnaert it is the calibration-geometry I/F. Typical values: dark terrain 0.02-0.10, bright highland 0.15-0.35.
sunaz=float [required]
Solar azimuth [degrees, from North clockwise]
0=North, 90=East, 180=South, 270=West.
sunelev=float [required]
Solar elevation [degrees above horizon]
Must be > 0 (sun above horizon).
model=string
Photometric model
Options: lambert, lommelseeliger, lunarlambert, minnaert, hapkehen, hapkeleg, lunarlambertmcewen
Default: minnaert
k=float
Minnaert K exponent
K=1: Lambertian; K=0.5: lunar-like. Used only with model=minnaert.
Default: 0.5
l=float
LunarLambert L mixing weight
L=0: Lambertian; L=1: Lommel-Seeliger. Used with model=lunarlambert.
Default: 1.0
wh=float
Hapke single-scattering albedo omega [0,1]. Used with Hapke models.
Default: 0.5
hh=float
Hapke opposition surge width h. Used with Hapke models.
Default: 0.0
b0=float
Hapke opposition surge amplitude B0. Used with Hapke models.
Default: 0.0
hg1=float
HapkeHen 1st HG asymmetry coefficient. Used with model=hapkehen.
Default: 0.0
hg2=float
HapkeHen 2nd component weight. Used with model=hapkehen.
Default: 0.0
bh=float
HapkeLeg Legendre b1 coefficient. Used with model=hapkeleg.
Default: 0.0
ch=float
HapkeLeg Legendre b2 coefficient. Used with model=hapkeleg.
Default: 0.0
theta=float
Hapke macroscopic roughness angle Theta [degrees]. Used with Hapke models.
Default: 0.0
niter=integer
Number of Horn-Brooks iterations
More iterations refine high-frequency topography further. 50-100 is sufficient for most applications.
Default: 50
lambda=float
Horn regularization weight lambda
Larger values suppress noise but reduce topographic amplitude. Typical range: 0.01 (steep terrain) to 0.5 (noisy data).
Default: 0.1

Table of contents

DESCRIPTION

p.photoclinometry refines a seed DEM using a single calibrated planetary reflectance image and a user-selected photometric model. The method is shape-from-shading (SFS), also called photoclinometry in the planetary-science literature.

The module implements the Horn-Brooks (1986) iterative gradient-domain algorithm: at each iteration the surface gradient field (p,q) is updated so that the photometric equation is better satisfied at every pixel, then the gradient field is integrated once at the end to recover the height field.

ALGORITHM

For a nadir-viewing geometry (sensor looking straight down), the predicted normalised brightness at a pixel whose surface normal is derived from gradients (p,q) is:

  cos(i) = (-p·sx - q·sy + sz) / sqrt(p² + q² + 1)
  cos(e) = 1               / sqrt(p² + q² + 1)
  f(p,q) = PhotoModel(g, i, e) / PhotoModel(0, 0, 0)

where (sx,sy,sz) is the unit sun vector in (East, North, Up) coordinates and g is the (constant) phase angle 90° − sun_elevation.

The Horn-Brooks update rule for each pixel:

  p_new = p̄ − fp · (f(p̄,q̄) − R) / (fp² + fq² + λ²)
  q_new = q̄ − fq · (f(p̄,q̄) − R) / (fp² + fq² + λ²)

where p̄,q̄ are the four-neighbour averages of the gradient field, R = I_obs / albedo is the target normalised brightness, and fp,fq are numerical partial derivatives of f with respect to p and q. λ (lambda) is the Horn regularisation weight.

After niter iterations, the gradient field is integrated to height by two-pass row+column cumulative summation and averaged. The mean elevation is then shifted to match the mean of the seed DEM.

PHOTOMETRIC MODELS

All models are provided by the p_photomodel library (same as p.photomet):

Model Description
lambert Lambertian: f = cos(i)
lommelseeliger Lommel-Seeliger: f = 2cos(i)/(cos(i)+cos(e))
lunarlambert Lunar-Lambert blend (parameter L)
minnaert Minnaert: f = cos(i)·(cos(i)·cos(e))^(K−1)
hapkehen Full Hapke (1981) with Henyey-Greenstein phase function
hapkeleg Full Hapke with Legendre polynomial phase function
lunarlambertmcewen McEwen (1991) polynomial-scaled Lunar-Lambert

PARAMETERS

Parameter Default Description
input= required Calibrated reflectance raster (I/F or equivalent)
output= required Output refined DEM raster
seed= optional Seed DEM raster; flat surface if omitted
albedo= required Surface normal albedo (dimensionless, in (0, 1])
sunaz= required Solar azimuth [degrees from North clockwise]
sunelev= required Solar elevation [degrees above horizon]
model= minnaert Photometric model
k= 0.5 Minnaert K exponent
l= 1.0 LunarLambert L mixing weight
wh= 0.5 Hapke single-scatter albedo
hh= 0.0 Hapke opposition surge width
b0= 0.0 Hapke opposition surge amplitude
hg1= 0.0 HapkeHen 1st asymmetry coefficient
hg2= 0.0 HapkeHen 2nd component weight
bh= 0.0 HapkeLeg Legendre b1
ch= 0.0 HapkeLeg Legendre b2
theta= 0.0 Hapke macroscopic roughness angle [degrees]
niter= 50 Number of Horn-Brooks iterations
lambda= 0.1 Horn regularisation weight

NOTES

EXAMPLE

# Photometrically correct a CTX image
p.photomet \
    input=ctx_raw \
    output=ctx_reflectance \
    model=minnaert k=0.5 \
    incidence=ctx_inc emission=ctx_emi phase=ctx_pha

# Derive topography from the corrected image
g.region raster=ctx_reflectance

p.photoclinometry \
    input=ctx_reflectance \
    output=ctx_sfs_dem \
    seed=mola_seed \
    albedo=0.17 \
    sunaz=225 \
    sunelev=35 \
    model=minnaert \
    k=0.5 \
    niter=100 \
    lambda=0.05

r.colors map=ctx_sfs_dem color=srtm
d.shade shade=ctx_sfs_dem color=ctx_reflectance brighten=40

REFERENCES

Horn, B.K.P. & Brooks, M.J. (1986). "The variational approach to shape from shading." Computer Vision, Graphics, and Image Processing, 33(2), 174–208.

Kirk, R.L. (1987). "A fast finite-element algorithm for two-dimensional photoclinometry." PhD thesis, California Institute of Technology.

Lohse, V., Heipke, C., & Kirk, R.L. (2006). "Derivation of planetary topography using multiscale photoclinometry." Planetary and Space Science, 54(7), 661–674.

Hapke, B. (1981). "Bidirectional reflectance spectroscopy: 1. Theory." Journal of Geophysical Research: Solid Earth, 86(B4), 3039–3054.

SEE ALSO

p.photomet, p.phocube, p.in.archive, r.slope.aspect, r.sunmask

AUTHOR

Yann Chemin

SOURCE CODE

Available at: p.photoclinometry source code (history)

Accessed: Sunday Nov 15 11:06:04 2026


Main index | Paint index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual