QCALVIEW40.21
User documentation · QCALVIEW 40.21

Calibrate a view

QCALVIEW

Calibrating a photographic view

What “calibration” means in QCALVIEW#

A calibrated QCALVIEW viewpoint links:

  • a geographic camera position;
  • an image projection model;
  • camera orientation;
  • field of view;
  • image dimensions and offsets;
  • terrain and GIS geometry.

The aim is not merely to make one object “look approximately right”. The aim is to make the whole image geometry agree with the territory as well as the available evidence allows.

The variables you are solving#

Viewpoint position#

The camera's X/Y location is often the most important external input. If it is wrong, a distant horizon may still look plausible while nearby projected geometry drifts significantly.

Use the best position available:

  • survey point;
  • GNSS observation;
  • reliable map location;
  • known tripod position;
  • a carefully inferred position when no survey exists.

Camera height / Z#

qcv_alt represents the camera height/Z used by QCALVIEW. With terrain-based operation it normally corresponds to the camera height above the sampled terrain at the viewpoint.

Do not confuse:

  • observer height above ground, and
  • absolute elevation.

Projection model#

Projection is not a cosmetic setting. It changes the mathematical relation between viewing angle and image position.

PINHOLE

Use for a normal rectilinear photograph or a rectilinear panorama crop.

Straight lines remain straight in the ideal projection. Large fields of view produce strong edge stretching, which is mathematically expected.

CYLINDRICAL

Use for cylindrical panoramas. Horizontal angle is mapped cylindrically, while vertical behaviour differs from an equirectangular sphere.

EQUIRECTANGULAR

Use for full spherical panoramas, typically 360 × 180.

Longitude/azimuth maps horizontally and elevation maps vertically. The ±180° seam is a real topological boundary and requires specific rendering handling.

Horizontal field of view — HFOV#

HFOV controls how much of the world fits horizontally in the image.

For a rectilinear photograph, HFOV can be related to focal length and sensor width. However, the most reliable value is the one corresponding to the actual delivered image after crop, stitching and correction, not necessarily the nominal lens marking.

A wrong HFOV often causes this symptom:

  • the centre fits reasonably well;
  • projected objects increasingly drift toward the edges.

Vertical field of view — VFOV#

VFOV can be derived from HFOV and image ratio in ordinary rectilinear cases, or specified explicitly when required by the image/projection.

Azimuth / yaw#

Yaw controls the horizontal viewing direction.

A constant left/right displacement across the whole image is often primarily a yaw issue, provided the viewpoint and FOV are correct.

Pitch#

Pitch controls vertical viewing direction.

A general vertical shift between terrain/objects and the photograph may indicate pitch, but first verify camera height and terrain.

Roll#

Roll rotates the camera around its optical axis.

Use it when horizontal or vertical references show a progressive tilt across the image. Do not use roll to compensate for terrain or panorama-stitching problems.

Image offsets#

Offsets are fine-adjustment parameters. They should normally come after projection, FOV and orientation have been solved.

If a large offset is required, ask why before accepting it.

Use this sequence unless the data provide a stronger constraint:

  1. verify CRS and viewpoint coordinates;
  2. assign the correct photograph;
  3. choose the projection model;
  4. select the correct DEM;
  5. set image size/crop assumptions;
  6. estimate HFOV/focal length;
  7. align yaw;
  8. align pitch;
  9. align roll;
  10. refine camera height if necessary;
  11. apply small offsets only at the end;
  12. verify the fit at several independent locations in the image;
  13. save the viewpoint state.

Using the terrain horizon#

The terrain horizon is powerful because it provides many geometric constraints at once.

A good workflow is:

  1. display the computed terrain horizon or ridgelines;
  2. identify stable photographed skyline sections;
  3. ignore vegetation and temporary objects that are not represented by the DEM;
  4. adjust projection/FOV/orientation;
  5. check several separated sections of skyline.

What a mismatch can mean#

Symptom Possible causes
Entire computed horizon shifted horizontally yaw, viewpoint position
Entire horizon shifted vertically pitch, camera height, terrain datum
Centre fits but edges drift HFOV or wrong projection
One side rises while the other falls roll
Only local areas disagree vegetation/buildings absent from DEM, DEM resolution/error
Panorama seam behaves strangely incorrect panorama projection or seam topology

Using known mapped geometry#

Roads, pylons, turbine positions, building corners, parcel edges and other stable mapped objects can complement the terrain horizon.

Prefer objects that are:

  • accurately mapped;
  • unambiguous in the photograph;
  • spatially distributed through the view;
  • at different distances when possible.

Do not calibrate against a single uncertain object.

GCP / control-point logic#

Ground control points are useful when you know that a geographic point corresponds to a specific image point.

They can help diagnose whether the error is dominated by:

  • orientation;
  • field of view;
  • image offset;
  • viewpoint position.

A control point is evidence, not magic. Several well-distributed points are more informative than many clustered points.

Monoplotting#

Monoplotting works in the opposite direction: instead of projecting a known map point into the image, you click the image and intersect the viewing ray with terrain.

It can provide:

  • image pixel location;
  • azimuth/elevation direction;
  • geographic point on terrain;
  • distance;
  • elevation;
  • a point or ray layer for further GIS work.

Uses include:

  • identifying an unknown photographed feature;
  • checking the location of a visible object;
  • creating reference points from an image;
  • documenting a visual-control point.

The result depends directly on the camera calibration and DEM quality.

Lens distortion#

QCALVIEW does not currently solve arbitrary lens distortion.

Cropping and resampling#

Cropping an image changes the effective field of view. Resizing does not change the angular field of view if the entire image is retained, but cropping does.

If an image has been cropped:

  • do not blindly reuse the original camera HFOV;
  • solve the FOV for the actual image used in QCALVIEW;
  • document the crop when traceability matters.

Panoramas#

Cylindrical panorama#

Check that the source really is cylindrical. A stitched panorama may have been exported into several possible projection formats.

Equirectangular panorama#

For a full panorama:

  • use EQUIRECTANGULAR;
  • set/verify 360 mode;
  • expect a seam at ±180°;
  • do not interpret seam duplication as ordinary perspective distortion.

How to decide that calibration is good enough#

There is no universal single-pixel threshold. Use evidence proportional to the study purpose.

A defensible calibration normally has:

  • a documented viewpoint position;
  • a justified projection model;
  • coherent FOV;
  • several independent terrain/object checks;
  • no obvious systematic drift across the image;
  • known uncertainties stated where relevant.

For a regulatory or adversarial comparison, keep a calibration record rather than relying only on visual memory.

Calibration checklist#

Before moving on to simulation:

  • CRS and viewpoint coordinates verified
  • camera height understood
  • source image identified
  • lens distortion corrected if needed
  • projection justified
  • HFOV/VFOV verified
  • yaw/pitch/roll checked
  • DEM selected and appropriate
  • horizon or independent geometry checked
  • offsets small and justified
  • viewpoint state saved

Next step#

Once the image and territory agree, continue with Visualize, simulate and communicate.