tl;dr guide

tl;dr guide#

This page is designed to provide a “bare bones” user guide to spymicmac/MicMac for processing KH-9 Hexagon mapping camera images or scanned air photos. It is presented primarily as a list of commands to run; if you would like a longer explanation of the different steps, see the additional guides here.

Note

If even this is too verbose for your tastes, you can view the sample “one big script” here.

setup#

Pre-processing and processing with MicMac requires a few files to be present in the directory - I recommend reading the setup tutorial first.

Note

If you are working with KH-9 Hexagon mapping camera images, you can skip to the pre-processing section below, as the convenience tool spymicmac.preprocessing.preprocess_kh9_mc() (command-line tool: preprocess_kh9_mc) will generate these files for the KH-9 Hexagon mapping camera.

Note

The rest of this guide assumes that you have the following directory structure:

project
├── id_fiducial.txt
├── Img1.tif
├── Img2.tif
...
├── MicMac-LocalChantierDescripteur.xml
├── Ori-InterneScan
│   └── MeasuresCamera.xml

where Img{n}.tif are the original scanned images.

Note

You will need a minimum of two images that overlap at least in part, because this is stereo photogrammetry.

pre-processing#

Before DEM and Orthophoto processing can happen, scanned images need to be pre-processed:

  • geometrically, so that they have a common format

  • radiometrically, to improve contrast and reduce noise

How these steps are done using spymicmac depends on what type of images you are working with.

KH-9 mapping camera#

Pre-processing KH-9 mapping camera images requires a number of different steps.

The convenience function spymicmac.preprocessing.preprocess_kh9_mc() (command-line tool: preprocess_kh9_mc) will perform all of these steps in order. All you need to do is run the command/function from the same directory where you have the .tgz (or .tar.gz) files.

Otherwise, the required steps are implemented in the following functions/modules, which should be run in order:

The re-sampled images will have OIS-Reech\_ appended to the filename, e.g.:

DZB1214-500206L002001.tif -> OIS-Reech_DZB1214-500206L002001.tif

These are the images that you will use for the remaining steps - you might want to create a new folder to place the original images.

Optional steps include:

  • cross removal (removing/erasing réseau markers) - this should be done before resampling the images (spymicmac.matching.remove_crosses())

  • radiometric pre-processing (e.g., de-noising with a gaussian filter or other contrast enhancements using spymicmac.image)

panoramic cameras#

As with the KH-9 mapping camera images, declassified panoramic camera images can be pre-processed using the convenience function spymicmac.preprocessing.preprocess_pan() (command-line tool: preprocess_pan). All you need to do is run the command/function from the same directory where you have the .tgz (or .tar.gz) files.

The required steps are:

Optional steps include:

  • radiometric pre-processing (de-noising with a gaussian filter, other contrast enhancements using spymicmac.image)

aerial photos#

Before processing scanned aerial images, you need to resample them to a common geometry using mm3d ReSampFid. The easiest way to do this is using the fiducial markers which are usually visible around the frame of the image.

You can manually identify the location of the fiducial markers using spymicmac.micmac.batch_saisie_fids():

from spymicmac.micmac import batch_saisie_fids
from glob import glob

imlist = glob('*.tif')
batch_saisie_fids(imlist, flavor='qt')

If you know the type of camera you are using, you can also use spymicmac.matching to try to automatically locate the fiducial markers in each image.

After you have identified the fiducial marker locations, use mm3d ReSampFid to re-sample the images. For example, to resample your images to a resolution of 14 microns (0.014 mm per pixel):

mm3d ReSampFid ".*tif" 0.014

The re-sampled images will have OIS-Reech\_ appended to the filename, e.g.:

AR5840034159994.tif -> OIS-Reech_AR5840034159994.tif

These are the images that you will use for the remaining steps - you might want to create a new folder to place the original images.

relative geometry#

Note

Panoramic camera processing with MicMac is not currently supported; however, these can be processed by following the example guides from Ames Stereo Pipeline (ASP).

spymicmac.asp has a number of functions that can be used to help set this processing up.

Note

If you have used spymicmac.preprocessing.preprocess_kh9_mc() or preprocess_kh9_mc, the tie points and camera calibration and orientation steps will all be run, and you can skip to computing the relative DEM and orthophoto.

Once the images have been re-sampled, the rest of the workflow is largely the same for both KH-9 mapping camera images and scanned air photos.

tie points#

First, you need to compute tie points for your re-sampled images, using mm3d Tapioca (or spymicmac.micmac.tapioca()):

mm3d Tapioca MulScale "OIS.*tif" 400 1200

from spymicmac import micmac
micmac.tapioca('OIS.*tif', res_low=400, res_high=1200)

camera calibration and orientation#

Next, you need to compute the relative orientation of the images, and calibrate the intrinsic camera parameters using mm3d Tapas (or spymicmac.micmac.tapas()):

mm3d Tapas FraserBasic "OIS.*tif" Out=Relative

from spymicmac import micmac
micmac.tapas(
    cam_model='FraserBasic',
    ori_out='Relative',
    img_pattern='OIS.*tif'
)

Tip

If you have a large number of images, you might want to initialize the calibration using a small number of good-quality images, before working on the whole set.

Tip

Using mm3d Martini (spymicmac.micmac.martini()) can help by initializing the image orientation.

Note

Tapas has a number of different camera calibration models available. You might wish to experiment with these to find one that works well.

visualizing the orientation#

You can visualize the orientation of the images using mm3d AperiCloud (or spymicmac.micmac.aperi()):

mm3d AperiCloud "OIS.*tif" Relative

from spymicmac import micmac
micmac.apericloud('Relative', 'OIS.*tif')

dem and orthomosaic#

If the orientation looks fine (no obvious camera outliers, point cloud looks roughly similar to the study area), you can process a relative DEM/orthophotos using mm3d Malt (or spymicmac.micmac.malt()):

mm3d Malt Ortho "OIS.*tif" Relative DirMEC=MEC-Relative NbVI=2 ZoomF=4 DefCor=0 CostTrans=4 EZA=1 SzW=3 Regul=0.1

from spymicmac import micmac
micmac.malt('OIS.*tif', 'Relative',
    zoomf=4,
    dirmec='MEC-Relative',
    cost_trans=4,
    szw=3,
    regul=0.1
)

mm3d Malt only orthorectifies the individual images; to create an orthomosaic, use the mm3d Tawny command (or spymicmac.micmac.tawny()):

mm3d Tawny Ortho-MEC-Relative Out=Orthophotomosaic.tif RadiomEgal=0

from spymicmac import micmac
micmac.tawny('MEC-Relative', radiomegal=False)

Note

If the image is very large, you may need to run spymicmac.micmac.mosaic_micmac_tiles() (or mosaic_micmac_tiles) to combine the tiles into a single image:

For the orthophoto, run the following from the project directory:

mosaic_micmac_tiles -filename Orthophotomosaic -imgdir Ortho-MEC-Relative

from spymicmac import micmac
micmac.mosaic_micmac_tiles('Orthophotomosaic', dirname='Ortho-MEC-Relative')

For the relative DEM, this will probably not be needed.

You can view the DEM or orthomosaic in a GIS software - if it looks okay, you can move on to the next steps. If not, you might need to work on the camera calibration or orientation.

absolute geometry#

Now that you have a DEM/orthophotos in relative geometry, you can use a reference image to transform them to an absolute geometry, and compute the final DEM/orthophotos.

registering the image#

Note

This step requires a DEM to find control points and estimate the absolute orientation of the images. In the examples below, I assume that you have named this file DEM.tif.

The main function to use here is spymicmac.register.register_relative() (or the command-line tool: register_relative):

register_relative MEC-Malt DEM.tif

register.register_relative(
    'MEC-Relative',
    'DEM.tif',
)

Note

If you have a file containing the image footprints, use the -footprints flag; otherwise, they will automatically be loaded from Footprints.gpkg (if it exists), or they will be downloaded from USGS Earth Explorer:

register_relative MEC-Malt DEM.tif -footprints Footprints.gpkg

register.register_relative(
    'MEC-Relative',
    'DEM.tif',
    footprints='Footprints.gpkg'
)

The file should contain a polygon for each image, with the name of the original image (minus the file extension) included in an ID column.

dem and orthomosaic#

After the absolute orientation has been estimated by registering the image, run mm3d Malt again with this new orientation to extract the final DEM and orthophoto:

mm3d Malt Ortho "OIS.*tif" TerrainFinal DirMEC=MEC-Malt NbVI=2 ZoomF=1 DefCor=0 CostTrans=4 EZA=1 SzW=3 Regul=0.1

from spymicmac import micmac
micmac.malt('OIS.*tif', 'TerrainFinal',
    zoomf=1,
    dirmec='MEC-Malt',
    cost_trans=4,
    szw=3,
    regul=0.1
)

To generate the orthomosaic, run the following command (or, using python):

mm3d Tawny Ortho-MEC-Malt Out=Orthophotomosaic.tif RadiomEgal=0

from spymicmac import micmac
micmac.tawny('MEC-Relative', radiomegal=False)

post-processing#

As a final step, run spymicmac.micmac.post_process() (post_process_micmac) to apply the AutoMask to the DEM and Orthomosaic:

post_process_micmac epsg_code desired_prefix MEC-Malt --do_ortho

from spymicmac import micmac
micmac.post_process(epsg_code, desired_prefix, 'MEC-Malt', do_ortho=True)

And that’s it. You should now have an orthorectified KH-9 (or air photo) mosaic, and a DEM. Enjoy.

Contents