From gnewarchaeology wiki
Jump to: navigation, search



CLI tools

The pipeline for transforming a set of images in a 3D model, and optionally generating ortho-photo, is made essentially of four ”complex” tools:

  • Pastis. In fact, this tool is no more than an interface to the well known Sift++;
  • Apero starts from tie points generated by Pastis, and optional complementary measurements, and generates external and internal orientations compatible with these measurements;
  • MICMAC starts from orientation generated by Apero and computes image matching;
  • Porto starts from individual rectified images, that have been optionally generated by MicMac, and generates a global ortho-photo; this tool is still in a very early stage.

There are several auxiliary tools that may be helpful for importing or exporting data at different steps of this pipeline:

  • BatchFDC for batching a set of commands;
  • Casa for computing analytic surface (cylinder...), from points cloud, very early stage;
  • ClipIm for clipping image;
  • ConvertIm for some image convertion;
  • Dequant for quantifying an image;
  • GrShade for compute shading from depth image;
  • MapCmd transforms a command working on a single file in a command working on a set of files;
  • CpFileVide to complete;
  • MpDcraw, an interface to the great dcraw offering some low-level service useful for image matching;
  • MyRename for image renaming, using modern regular expression and giving the possibility to integrate xif data in the new name, tricky but necessary in the existing pipeline;
  • Nuage2Ply, a tool to convert depth map in point cloud;
  • SaisieMasq, a user friendly (compared to others...) tool to create mask upon an image;
  • ScaleIm, tool for scaling image;
  • ScaleNuage, tool for scaling internal representation of point cloud;
  • tiff info, tool for giving information about a tiff file;
  • to8Bits, tool for converting 16 or 32 bit image in a 8 bit image;
  • SupMntIm, tool for generating a superposition of image and MNT in hypsometry and level curves;
  • PanelIm, gather images in a panel.

All in one command

  • Tapioca, full automatic tie points computation works. In fact, this tool is no more than an interface to Pastis;
  • Tapas, full automatic orientation computation works;
  • full automatic matching is not achieved, there exist some piece of code that may be already usefull for some users;
  • Malt, semi-automatic matching works;

The universal command

The syntax for calling the tools is based on a unique command mm3d:

mm3d Command arg1 arg2 ... argn NameOpt1=Argot1 ...

For backward compatibility (support of existing user’s script), the old syntax is still supported for most of the existing tool. However, it is recommended for new scripts to be based on the universal command mm3d.

For the main command, a log file mm3d-LogFile.txt is created, this file stores a global history of all the processing.


The simplest case of use of Tapioca is when you only want to compute tie points between all the pairs of a set of images.

Tapioca All Files Size ArgOpt=
  • Files is the concatenation of the directory where the files are located with a regular expression used as a filter on the existing files of the directory;
  • Size is used to shrink the images. It does not specify a scale but the desired width for shrinking the images: −1 means, conventionally, no shrinking; if the initial image has a width of 5000, and the value is 2000, it will specify a scaling of 0.4.

The only optional arguments are those common to all modes (ExpTxt and ByP):

  • ExpTxt=1 means that the export is made in text mode.
mm3d Tapioca All "../micmac_data/ExempleDoc/Boudha/IMG_[0-9]{4}.tif" -1 ExpTxt=1


Linear structures

It often occurs that the photos canvas has a linear structure. In this case, you know that K th can only have tie points with images in the interval [K − δ, K + δ]; giving this information to Tapioca can save a lot of time.

Tapioca Line Files Size delta ArgOpt=

Multi scale

The mode MulScale can save significant computation time on large sets of images. A first computation of tie points is made for all the pairs of images at very low resolution (so it is quite fast). Then the computation, at the desired resolution, is done only for the pairs having, at low resolution, a number of tie points exceeding a given threshold.

Tapioca MulScale Files SizeLow Size NbMinPt= ArgOpt=
  • NbMinPt is the threshold on the number of tie points detected at low resolution, its default value is 2.

File of pairs

Sometimes, you will have external information (like embedded GPS) that allows you to know which pairs of images are potential candidates for tie points. The easiest way to communicate your information is to write a file containing the explicit list of pairs of images. It is possible in the File mode.

Tapioca File NameOfFile Size ArgOpt=

The file containing the pairs must have the following structure:

<?xml version="1.0" ?>
   <Cple>IMG_5564.tif IMG_5565.tif</Cple>
   <Cple>IMG_5574.tif IMG_5575.tif</Cple>
   <Cple>IMG_5580.tif IMG_5579.tif</Cple>
   <Cple>IMG_5581.tif IMG_5582.tif</Cple>


The general tool for computing orientation of images is Apero. Tapas is a tool offering most of the possibilities of Apero for computing purely relative orientations.

Tapas ModeCalib PatternImage
  • ModeCalib is an enumerated value specifying a model of calibration;
  • PatternImage is a pattern specifying the subset of images to orientate.

The possible value of ModeCalib are:

  • RadialExtended a model with radial distorsion (10 degrees of freedom);
  • RadialBasic a ”subset” of previous model (5 degrees of freedom);
  • Fraser a radial model, with decentric and affine parameters (12 degrees of freedom);
  • FraserBasic same as previous with (10 degrees of freedom);
  • FishEyeEqui a model adapted for diagonal fisheyes equilinear (14 degrees of freedom);
  • HemiEqui same model as previous, but adapted to hemispheric equilinear fisheye;
  • AutoCal and Figee , with this tag no model is defined, all the calibration must have a value.


Successive calls

With large data set, it is often preferable to proceed in two step:

  1. compute on a small set of image a value of intrinsic calibration. This set of image should be favorable to calibration; ideally, it should fullfil the following requirements:
    • all image converging to same part of the scene,to facilitate the computation of external orientation
    • a scene with sufficient depth variation ,to have accurate focal length estimation;
    • a image acquisition where there position of the same ground points are located at very different position in the different images where they are seen, this is to have accurate estimation of distortion; this can be obtained by rotating the camera;
  2. use the calibration obtained on the small set as an initial value for the global orientation.

Multiple lenses


Camera and Exif handling

For each camera it has to handle, when the user do not provide a calibration file, Tapas has to build an initial value:

  • for the distorsion , the initial value is null;
  • for the principal point the initial value is a at center of image;
  • for the focal lens Tapas must compute an initial value in pixel, this information is computed with the help of xif[] data.

Xif meta data contain a tag indicating the name of the camera. This camera name is used by the different tools as an entry in data bases containing informations absent from xif files. These data base can be located in three different files:

  • include/XML MicMac/DicoCamera.xml, it is part of the MicMac distribution;
  • include/XML User/DicoCamera.xml, you have to create it and put inside the descritption of all the camera that you will use currently;
  • MicMac-LocalChantierDescripteur.xml, in your working directory when this file exists.

Sometimes, the xif file does not contain the expected information. In this case, the information can be indicated ”dynamically” by creating specific key in the MicMac-LocalChantierDescripteur.xml. Another solution to deal with missing xif info is to use the modifying facilities offered by the exiv2[] command.

Other orientation tools



Campari is an interface to Apero, for compensation of heterogenous measures, that is: tie points and ground control points (GCP).

Campari Arg1 OriIn OriOut GCP=[]

Arg1: pattern specifying the set of images; OriIn: pattern specifying the directory where orientations are located; OriOut: pattern specifying the directory where to write output orientations; GCP, optional: specifying the ground and image measures files.

Mandatory part of GCP:

  • xml file with 3D coordinates for GCP
  • GCP ground uncertainty
  • xml file with 2D coordinates for GCP
  • GCP image uncertainty
Campari "MyDir\IMG_.*.jpg" OriIn OriOut GCP=[GroundMeasures.xml,0.1,ImgMeasures.xml,0.5]


The xml file containing 3D coordinates has to verify a specific format. A tool to convert existing coordinates listing files into this format is proposed with GCPConvert.

SaisiePointsInit & SaisiePointsPredic

The xml file containing 2D coordinates can be generated using interfaces SaisiePointsInit and SaisiePointsPredic


Simplified version of the <BasculeOrientation> mechanisms, used when global transformation of the orientation is required. The tools for bascule are:


SBGlobBascule is a tool for ”scene based global” bascule, it is used when no absolute information is avalaible but the user still wishes to give some physicall meaning to the orientation.


GCPBascule is a tool for using ground control point (GCP) to make a global transformation from a generally purely relative orientation to an orientation in the system of the GCP. The GCPBascule command allows to transform a purely relative orientation, as computed with Tapas, in an absolute one, as soon as there is at least 3 GCP whose projection are known in at least 2 images.

GCPBascule "IMGP41((6[7-9])|([7-8][0-9])).JPG" Mur Ground Ground-Pts3D.xml GroundMeasure.xml


RepLocBascule is a tool usefull to define a local repair without changing the orientation.


CenterBascule for using embeded GPS on submit to make a global transformation from a generally purely relative orientation to an absolute orientation.

Full automatic matching


To compute a posteriori the structure of an acquisition, the first thing is to know, for each potential master image, what would be the best set of secondary images. This what does the tool AperoChImSecMM.

mm3d AperoChImSecMM ".*JPG" All

The Ori-All directory contains files ImSec-XXXX.xml. Each file contains possible sets of secondary images.


Each Sol contain a possible set of secondary images. There is several sets because there is no universal criteria to define the best set. Although to facilitate an automatic exploitation, each set has an associated score. These result will be used implicitly in the following automatic tools.


The tool MMInitialModel is used to create fully automatically a regularly dense but coarse 3D model out of a set of images. Although its main purpose is to create a model that will be used to drive future tools, it can already be used now for those who only need a regular coarse 3D model. This tool requires that the AperoChImSecMM command has been executed before.

mm3d MMInitialModel ".*JPG" All DoPly=1


The tool MMTestAllAuto is a precursor of the fully automatic tool that will be executed, driven by the coarse model of MMInitialModel . It assume that AperoChImSecMM has been executed, and compute a ”fine” 3D model for a given master image using a predefined parametrization of MICMAC. The tool works generally well when the master image has ”good” secondary image. Conversely, the result can be almost empty in the other cases.

Semi-automatic matching

Even when the full automatic matching will be available, many use will need to have is some circumstances a finer control of the process.


To run the matching process (with MicMac or Malt) the programm must decide which space has to be explored. If no information is given, the programs will adopt a default strategy it will select points of the scene that are visible on at least N images 14 , making the assomption that the scene is globally flat. Althoug this strategy may be perfectly ok on aerial acquisition, in the the general case it may create a uselessly too large area.

An easy way to indicate which part of the scene you want to use, is to create a mask on a rectified mosaic. The tool Tarama allows to create such mosaic.


Malt is a simplified interface to MicMac. Currently it can handle matching in ground geometry.

Malt Type Pattern Orient

Type specifys the kind of matching required:

  • Ortho , for a matching adapted to ortho photo generation;
  • UrbanMNE , for a matching adapted to urban digital elevation model;
  • GeomImage , for a matching in ground image geometry;


The simplified tool for generating ortho mosaic is Tawny, it is an interface to the Porto tool. The use of Tawny is quite simple because it assumes that the data have been correctly prepared and organized during the matching process. Practically this is done when the macthing has been made using Malt and I recommand to only use Tawny in conjonction with Malt. In Ortho Mode, Malt has created a set of individual ortho images, associated mask, incidence image, etc... in a directory Ortho-MEC-Malt/. The job of Tawny is essentially to merge these data and to optionnaly do some radiometric equalization.

Tawny Ortho-MEC-Malt/ DEq=1 DegRap=1 ImPrio=Ort_IMG_.* SzV=3 CorThr=0.6 NbPerIm=5e4


External links