spymicmac.micmac

spymicmac.micmac#

spymicmac.micmac is a collection of tools for interfacing with MicMac commands, as well as for working with the various XML and other files created/used by MicMac.

setup#

These methods are used to set up the different files needed to run MicMac.

spymicmac.micmac.create_localchantier_xml(name='KH9MC', short_name='KH-9 Hexagon Mapping Camera', film_size=(460, 220), pattern='.*', focal=304.8, add_sfs=False, cam_csv=None)[source]#

Create a MicMac-LocalChantierDescripteur.xml file for a given camera. Default is the KH-9 Hexagon Mapping Camera.

Parameters:

  • name (str) – The name to use for the camera

  • short_name (str) – A short description of the camera

  • film_size (tuple[int | float, int | float]) – the film size (width, height) in mm

  • pattern (str) – the matching pattern to use for the images

  • focal (float) – the nominal focal length, in mm

  • add_sfs (bool) – use SFS to help find tie points in low-contrast images

  • cam_csv (str | Path | None) – the CSV file containing parameters for multiple cameras

Return type:

None

spymicmac.micmac.generate_multicam_csv(patterns=None, prefix='OIS-Reech_', fn_out='camera_defs.csv', name='', short_name='', film_width='', film_height='', focal='')[source]#

Create a CSV file with camera parameters than can be read by create_localchantier_xml() to use images acquired by multiple cameras.

Can be used to create a blank CSV template to be filled out manually, or generated using the optional function arguments.

Parameters:

  • patterns (list | None) – a list of filename patterns corresponding to each camera

  • prefix (str) – an optional prefix to add to the matching patterns

  • fn_out (str) – the name of the CSV file to create

  • name (str | list) – the name to give each camera. Must be unique.

  • short_name (str | list) – the “short name” description of each camera. Does not need to be unique.

  • film_width (str | list) – the width in mm of the frame for each camera.

  • film_height (str | list) – the height in mm of the frame for each camera.

  • focal (str | float | list) – the focal length of each camera, in mm.

Return type:

None

spymicmac.micmac.create_measurescamera_xml(fn_csv, ori='InterneScan', translate=False, name='gcp', x='im_col', y='im_row')[source]#

Create a MeasuresCamera.xml file from a csv of fiducial marker locations.

Parameters:

  • fn_csv (str | Path | DataFrame) – the filename of the CSV file, or a pandas DataFrame.

  • ori (str) – the Ori directory to write the MeasuresCamera.xml file to. Defaults to (Ori-)InterneScan.

  • translate (bool) – translate coordinates so that the origin is the upper left corner, rather than the principal point

  • name (str) – the column name in the csv file corresponding to the point name

  • x (str) – the column name in the csv file corresponding to the image x location

  • y (str) – the column name in the csv file corresponding to the image y location

Return type:

None

spymicmac.micmac.generate_measures_files(joined=True)[source]#

Create id_fiducial.txt, MeasuresCamera.xml, and Tmp-SL-Glob.xml files for KH-9 Hexagon mapping camera images.

Parameters:

joined (bool) – generate files for joined scene (220x460 mm) instead of half (220x230mm)

Return type:

None

spymicmac.micmac.init_autocal(imsize=(32200, 15400), framesize=(460, 220), focal=304.8, camname='KH9MC')[source]#

Create an AutoCal xml file for use in the Tapas step. Default values are for KH-9 Hexagon Mapping Camera.

When calling mm3d Tapas, be sure to use “InCal=Init”:

mm3d Tapas RadialBasic “OIS.*tif” InCal=Init Out=Relative LibFoc=0

The name of the file changes based on the focal length and camera name. Using the default values of foc=304.8 and camname=’KH9MC’ creates the following file in Ori-Init:

AutoCal_Foc-KH9MC_304800.xml

Parameters:

  • imsize (tuple[int, int]) – the size of the image (width, height) in pixels

  • framesize (tuple[int | float, int | float]) – the size of the image (width, height) in mm

  • focal (float) – nominal focal length, in mm

  • camname (str) – the camera short name to use

Return type:

None

spymicmac.micmac.write_xml(fn_img, fn_mask='./MEC-Malt/Masq_STD-MALT_DeZoom1.tif', fn_xml=None, geomname='eGeomMNTEuclid')[source]#

Given a GDAL dataset, create a MicMac xml worldfile.

Parameters:

  • fn_img (str) – the filename of the image.

  • fn_mask (str) – the filename of the mask file

  • fn_xml (None | str) – the filename of the xml file to create (default: fn_img + ‘.xml’)

  • geomname (str) – the MicMac Geometry name to use

Return type:

None

micmac interface#

These methods are used to interface with their corresponding mm3d commands, based on where they fall in the tutorials processing workflow.

  • pre-processing: the steps taken to get the images ready for processing

  • relative: the steps taken to estimate the intrinsic camera parameters (e.g., principal point, radial distortion, affine/decentric correction) and the relative external orientation of the images

  • absolute: the steps taken to process the images in an absolute (“real-world”) geometry: registration and bundle block adjustment (BBA), dense matching and orthorectification

  • post-processing: the steps taken to correct or adjust the results after processing

pre-processing#

spymicmac.micmac.batch_saisie_fids(imlist, flavor='qt', fn_cam=None, clean=True, gamma=None)[source]#

Run SaisieAppuisInit to locate the fiducial markers for a given list of images.

Parameters:

  • imlist (list) – the list of image filenames.

  • flavor (str) – which version of SaisieAppuisInit to run. Must be one of [qt, og]

  • fn_cam (None | str) – the filename for the MeasuresCamera.xml file

  • clean (bool) – remove any image files in Tmp-SaisieAppuis

  • gamma (None | float) – Gamma adjustment value for Saisie

Return type:

None

spymicmac.micmac.estimate_measures_camera(approx, pairs, ori='InterneScan', scan_res=2.5e-05, how='mean', write_xml=True, inverted=True)[source]#

Use a set of located fiducial markers to create a MeasuresCamera file using the average location of each fiducial marker.

Parameters:

  • approx (DataFrame | dict) – a dataframe of approximate fiducial marker locations, or a dict of fiducial marker names and their angle with respect to the principal point. i.e., a mid-side marker on the right side of the frame should have an angle of 0, the fiducial marker in the upper right-hand corner should have an angle of 45° (pi / 4), a mid-side marker on the top of the frame should have an angle of 90° (pi / 2), and so on.

  • pairs (list[tuple]) – a list of pairs of co-linear fiducial markers

  • ori (str) – The Ori- directory containing the MeasuresIm files

  • scan_res (float) – the scanning resolution of the images in m

  • how (str) – what average to use for the output locations. Must be one of [mean, median].

  • write_xml (bool) – write the MeasuresCamera.xml file in addition to a CSV

  • inverted (bool) – the y-axis is inverted.

Return type:

None

finding tie points#

spymicmac.micmac.tapioca(img_pattern='OIS.*tif', res_low=400, res_high=1200, fn_neighbours=None, exp_txt=False, subscript=None)[source]#

Run mm3d Tapioca to find image tie points.

Parameters:

  • img_pattern (str) – The image pattern to pass to Tapioca (default: OIS.*tif)

  • res_low (int) – the size of the largest image axis, in pixels, for low-resolution matching

  • res_high (int) – the size of the largest image axis, in pixels, for high-resolution matching

  • fn_neighbours (str | Path | None) – filename for an optional XML file containing image pairs

  • exp_txt (bool) – export the tie points in txt (ascii) format

  • subscript (None | str) – the subscript to append to the Homol directory name (default is no subscript)

Return type:

int

spymicmac.micmac.write_neighbour_images(imlist=None, footprints=None, name_field='ID', prefix='OIS-Reech_', file_ext='.tif', dataset='AERIAL_COMBIN', from_homol=False, img_pattern='OIS*.tif', dir_homol='Homol')[source]#

Write an xml file containing image pairs for processing with Tapioca, using either image footprints or a homologue directory to determine pairs of overlapping images.

Parameters:

  • imlist (list | None) – a list of (original) image names to use (e.g., without ‘OIS-Reech_’)

  • footprints (str | Path | GeoDataFrame | None) – an optional filename for a vector dataset of image footprints or a GeoDataFrame of image footprints. If None, uses spymicmac.data.get_usgs_footprints to download footprints based on imlist.

  • name_field (str) – the field in fprints table that contains the image name

  • prefix (str) – the prefix attached to the image name read by Tapioca

  • file_ext (str) – the file extension for the images read by Tapioca

  • dataset (str) – the USGS dataset name to search if no footprints are provided

  • from_homol (bool) – get a list of pairs based on homologue files

  • img_pattern (str) – the image pattern to pass to glob to get a list of filenames

  • dir_homol (str) – the directory where the homologue files are

Return type:

None

spymicmac.micmac.pairs_from_footprints(imlist, footprints=None, name_field='ID', prefix='OIS-Reech_', file_ext='.tif', dataset='AERIAL_COMBIN', return_overlap=False)[source]#

Using a list of images and a collection of image footprints, return a list of potential image pairs for processing with Tapioca.

Parameters:

  • imlist (list) – a list of (original) image names to use (e.g., without ‘OIS-Reech_’)

  • footprints (str | Path | GeoDataFrame | None) – an optional filename for a vector dataset of image footprints or a GeoDataFrame of image footprints. If None, uses spymicmac.data.get_usgs_footprints to download footprints based on imlist.

  • name_field (str) – the field in fprints table that contains the image name

  • prefix (str) – the prefix attached to the image name read by Tapioca

  • file_ext (str) – the file extension for the images read by Tapioca

  • dataset – the USGS dataset name to search if no footprints are provided

  • return_overlap (bool) – return the percent overlap for each pair

Returns:

  • pairs – a list of tuples representing image pairs

  • overlaps – a list of the percent overlap for each pair, if return_overlap is True

Return type:

list | tuple[list, list]

relative geometry#

The following methods are used for working with images in a relative geometry:

spymicmac.micmac.martini(img_pattern='OIS.*tif', in_ori=None, ori_out=None, quick=True, exp_txt=False)[source]#

Run mm3d Martini, which provides a quick way to orient images without solving for camera parameters.

Parameters:

  • img_pattern (str) – The image pattern to pass to Martini

  • in_ori (None | str) – the orientation directory to use to initialize the calibration

  • ori_out (None | str) – the name of the output orientation directory

  • quick (bool) – run Martini in “quick” mode

  • exp_txt (bool) – tie points (Homol) are in txt (ascii) format

Return type:

int

spymicmac.micmac.tapas(cam_model, ori_out=None, img_pattern='OIS.*tif', in_cal=None, in_ori=None, lib_foc=True, lib_pp=True, lib_cd=True, dir_homol=None, exp_txt=False)[source]#

Run mm3d Tapas with a given camera calibration model.

Some basic camera calibration models for air photos:

  • RadialBasic

  • RadialStd

  • RadialExtended

  • FraserBasic

  • Fraser

See MicMac docs for a full list/explanation of the camera models.

Parameters:

  • cam_model (str) – the camera calibration model to use.

  • ori_out (str | None) – the output orientation. Will create a directory, Ori-{ori_out}, with camera parameter files.

  • img_pattern (str) – the image pattern to pass to Tapas

  • in_cal (str | None) – an input calibration model to refine

  • in_ori (str | None) – a set of orientations to initialize the calibration

  • lib_foc (bool) – allow the focal length to be calibrated

  • lib_pp (bool) – allow the principal point to be calibrated

  • lib_cd (bool) – allow the center of distortion to be calibrated

  • dir_homol (str | None) – the name of the Homol directory to use (default: Homol)

  • exp_txt (bool) – tie points (Homol) are in txt (ascii) format

Return type:

int

absolute geometry#

spymicmac.micmac.bascule(in_gcps, outdir, img_pattern, sub, ori, outori='TerrainRelAuto', fn_gcp='AutoGCPs', fn_meas='AutoMeasures')[source]#

Interface for running mm3d GCPBascule and reading the residuals from the resulting xml file.

Parameters:

  • in_gcps (DataFrame) – a DataFrame with the GCPs that are being input to Campari.

  • outdir (str) – the output directory where the AutoGCPs.xml file is saved.

  • img_pattern (str) – the match pattern for the images being input to Campari (e.g., “OIS.*tif”)

  • sub (str) – the name of the block, if multiple blocks are being used (e.g., ‘_block1’). If not, use ‘’.

  • ori (str) – the name of the orientation directory (e.g., Ori-Relative).

  • outori (str) – the name of the output orientation directory.

  • fn_gcp (str) – the filename pattern for the GCP file. The file that will be loaded will be fn_gcp + sub + ‘.xml’ (e.g., default: AutoGCPs -> AutoGCPs_block0.xml)

  • fn_meas (str) – the filename pattern for the measures file. The file that will be loaded will be fn_meas + sub + ‘-S2D.xml’ (e.g., default: AutoMeasures -> AutoMeasures_block0-S2D.xml)

Returns:

out_gcps – the input gcps with the updated Bascule residuals.

Return type:

DataFrame

spymicmac.micmac.campari(in_gcps, outdir, img_pattern, sub, dx=None, sig_abs=None, sig_pix=0.5, allfree=True, fn_gcp='AutoGCPs', fn_meas='AutoMeasures', inori='TerrainRelAuto', outori='TerrainFinal', dir_homol='Homol', exp_txt=False, rap_txt=None)[source]#

Interface for running mm3d Campari and reading the residuals from the residual xml file.

Parameters:

  • in_gcps (DataFrame) – a DataFrame with the GCPs that are being input to Campari.

  • outdir (str) – the output directory where the AutoGCPs.xml file is saved.

  • img_pattern (str) – the match pattern for the images being input to Campari (e.g., “OIS.*tif”)

  • sub (str) – the name of the block, if multiple blocks are being used (e.g., ‘_block1’). If not, use ‘’.

  • dx (int | float | None) – the pixel resolution of the reference image. If set, sig_abs is calculated as dx / 4. One of dx or sig_abs must be set.

  • sig_abs (int | float | None) – the absolute uncertainty in position for the GCP location. One of dx or sig_abs must be set.

  • sig_rel – the uncertainty in position for the GCP location in the image.

  • allfree (bool) – run Campari with AllFree=1 (True), meaning that all camera parameters will be optimized, or AllFree=0 (False), meaning that only the orientation will be optimized.

  • fn_gcp (str) – the filename pattern for the GCP file. The file that will be loaded will be fn_gcp + sub + ‘.xml’

  • fn_meas (str) – the filename pattern for the measures file. The file that will be loaded will be fn_meas + sub + ‘-S2D.xml’

  • inori (str) – the input orientation to Campari

  • outori (str) – the output orientation from Campari

  • dir_homol (str) – the Homologue directory to use

  • exp_txt (bool) – tie points (Homol) are in txt (ascii) format

  • rap_txt (str | Path | None) – filename for the per-point residual report, if desired

  • sig_pix (int | float | None)

Returns:

out_gcps – the input gcps with the updated Campari residuals.

Return type:

DataFrame

spymicmac.micmac.iterate_campari(gcps, out_dir, match_pattern, subscript, dx=None, sig_abs=None, sig_pix=0.5, fn_gcp='AutoGCPs', fn_meas='AutoMeasures', rel_ori='Relative', inori='TerrainRelAuto', outori='TerrainFinal', homol='Homol', allfree=True, max_iter=5, rap_txt=None)[source]#

Run Campari iteratively, refining the orientation by removing outlier GCPs and Measures, based on their fit to the estimated camera model.

Parameters:

  • gcps (DataFrame) – a DataFrame with the GCPs that are being input to Campari.

  • out_dir (str) – the output directory where the GCP and Measures files are located.

  • match_pattern (str) – the match pattern for the images being input to Campari (e.g., “OIS.*tif”)

  • subscript (str) – the name of the block, if multiple blocks are being used (e.g., ‘_block1’). If not, use ‘’.

  • dx (int | float | None) – the pixel resolution of the reference image. If set, sig_abs is calculated as dx / 4. One of dx or sig_abs must be set.

  • sig_abs (int | float | None) – the absolute uncertainty in position for the GCP location. One of dx or sig_abs must be set.

  • sig_rel – the uncertainty in position for the GCP location in the image.

  • fn_gcp (str) – the filename pattern for the GCP file. The file that will be loaded will be fn_gcp + sub + ‘.xml’ (e.g., default: AutoGCPs -> AutoGCPs_block0.xml)

  • fn_meas (str) – the filename pattern for the measures file. The file that will be loaded will be fn_meas + sub + ‘-S2D.xml’ (e.g., default: AutoMeasures -> AutoMeasures_block0-S2D.xml)

  • rel_ori (str) – the name of the relative orientation to input to GCPBascule

  • inori (str) – the input orientation to Campari

  • outori (str) – the output orientation from Campari

  • homol (str) – the Homologue directory to use

  • allfree (bool) – run Campari with AllFree=1 (True), meaning that all camera parameters will be optimized, or AllFree=0 (False), meaning that only the orientation will be optimized.

  • max_iter (int) – the maximum number of iterations to run.

  • rap_txt (str | Path | None) – filename for the per-point residual report, if desired

  • sig_pix (int | float | None)

Returns:

gcps – the gcps with updated residuals after the iterative process.

Return type:

DataFrame

spymicmac.micmac.checkpoints(img_pattern, ori, fn_cp, fn_meas, fn_resids=None, ret_df=True)[source]#

Interface to run GCPCtrl to calculate checkpoint residuals for a given Orientation.

Parameters:

  • img_pattern (str) – the match pattern for the images being input to Campari (e.g., “OIS.*tif”)

  • ori (str) – the full name of the orientation directory to use (e.g., Ori-TerrainFinal)

  • fn_cp (str) – the filename of the CPs.xml file to use

  • fn_meas (str) – the filename of the CP Measures.xml file to use

  • fn_resids (str) – the (optional) filename to write the residuals for each checkpoint to

  • ret_df (bool) – return a DataFrame with the residuals for each checkpoint

Returns:

cp_resids – a DataFrame with residuals for each checkpoint

Return type:

None | DataFrame

spymicmac.micmac.get_autogcp_locations(ori, meas_file, imlist)[source]#

Find location of automatically-detected control points in individual images using mm3d XYZ2Im.

Parameters:

  • ori (str) – The orientation directory name (e.g., Ori-Relative)

  • meas_file (str | Path) – The Measures file to find image locations for

  • imlist (list) – a list of image names

Return type:

None

post-processing#

spymicmac.micmac.post_process(projstr, out_name, dirmec, out_dir='post_processed', do_ortho=True, ind_ortho=False, do_ply=False)[source]#

Apply georeferencing and masking to the final DEM and Correlation images (optionally, the orthomosaic as well).

Output files are written as follows:

  • DEM: {out_dir}/{out_name}_Z.tif

  • Hillshade: {out_dir}/{out_name}_HS.tif

  • Correlation: {out_dir}/{out_name}_CORR.tif

  • Orthomosaic: {out_dir}/{out_name}_Ortho.tif

  • Pointcloud (.ply): {out_dir}/{out_name}.ply

Parameters:

  • projstr (str | int) – A string corresponding to the DEM’s CRS that GDAL can use to georeference the rasters, or an int corresponding to the EPSG code for the DEM’s CRS.

  • out_name (str) – The name that the output files should have.

  • dirmec (str) – The MEC directory to process files from (e.g., MEC-Malt)

  • do_ortho (bool) – Post-process the orthomosaic in Ortho-{dirmec}, as well. Assumes that you have run mm3d Tawny with Out=Orthophotomosaic first.

  • ind_ortho (bool) – apply a mask to each individual ortho image

  • do_ply (bool) – run mm3d Nuage2Ply to create point cloud in PLY format.

  • out_dir (str | Path)

Return type:

None

spymicmac.micmac.mosaic_micmac_tiles(filename, dirname='.')[source]#

Re-stitch images tiled by MicMac.

Parameters:

  • filename (str) – MicMac filename to mosaic together (e.g., Orthophotomosaic)

  • dirname (str | Path) – directory containing images to mosaic

Return type:

None

spymicmac.micmac.banana(fn_dem, fn_ref, deg=2, dz_thresh=200.0, fn_mask=None, spacing=100)[source]#

Interface for running mm3d Postproc Banana, for computing a polynomial correction to a “banana” or dome.

Parameters:

  • fn_dem (str | Path) – the filename of the input DEM to correct

  • fn_ref (str | Path) – the filename of the reference DEM to use for the correction

  • deg (int) – the degree of the polynomial correction (0 - 3)

  • dz_thresh (float) – the threshold elevation difference between the reference and input DEMs

  • fn_mask (str | Path | None) – an (optional) exclusion mask to use for the reference DEM

  • spacing (int) – the sample spacing of the DEM to write, in pixels

Return type:

None

general#

spymicmac.micmac.apericloud(ori, img_pattern='OIS.*tif', fn_out=None, with_points=True, with_cam=True, exp_txt=False)[source]#

Run mm3d AperiCloud to create a point cloud layer

Parameters:

  • ori (str) – the input orientation to use

  • img_pattern (str) – the image pattern to pass to AperiCloud

  • fn_out (str | None) – the output filename (default: AperiCloud_{ori}.ply)

  • with_points (bool) – display the point cloud

  • with_cam (bool) – display the cameras

  • exp_txt (bool) – tie points (Homol) are in txt (ascii) format

Return type:

int

spymicmac.micmac.malt(imlist, ori, zoomf=1, zoomi=None, dirmec='MEC-Malt', seed_img=None, seed_xml=None, resol_terr=None, resol_ort=None, cost_trans=None, szw=None, regul=None, do_ortho=True, do_mec=True, clean=False)[source]#

Run mm3d Malt Ortho.

Parameters:

  • imlist (str | list) – either a match pattern (e.g., OIS.*tif) or an iterable object of image filenames.

  • ori (str) – the orientation directory to use for Malt.

  • zoomf (int) – the final Zoom level to use

  • zoomi (None | int) – the initial Zoom level to use (default: not set)

  • dirmec (str) – the output MEC directory to create

  • seed_img (str | Path | None) – a DEM to pass to Malt as DEMInitImg. Note that if seed_img is set, seed_xml must also be set. If used, it is recommended to set zoomi to be approximately equal to the DEM resolution - i.e., if the ortho resolution is 5 m and the seed DEM is 20 m, ZoomI should be 4.

  • seed_xml (str | Path | None) – an XML file corresponding to the seed_img

  • resol_terr (float | int | None) – the resolution of the output DEM, in ground units (default: computed by mm3d)

  • resol_ort (float | int | None) – the resolution of the ortho images, relative to the output DEM - e.g., resol_ort=1 means the DEM and Orthoimage have the same resolution (default: 2.0)

  • cost_trans (float | int | None) – cost to change from correlation to decorrelation (default: 2.0)

  • szw (int | None) – the half-size of the correlation window to use - e.g., szw=1 means a 3x3 correlation window.

  • regul (float | None) – the regularization factor to use. Lower values mean higher potential variability between adjacent pixels, higher values (up to 1) mean smoother outputs

  • do_ortho (bool) – whether to generate the orthoimages

  • do_mec (bool) – whether to generate an output DEM

  • clean (bool) – remove temporary/intermediate files after finishing.

Return type:

int

spymicmac.micmac.tawny(dirmec, radiomegal=False)[source]#

Run mm3d Tawny to create an orthomosaic.

Parameters:

  • dirmec (str) – the MEC directory to use

  • radiomegal (bool) – run Tawny with RadiomEgal=1

Return type:

int

homologous points#

The following methods are used for filtering homologous point files, or for finding connected blocks of images based on their shared tie points.

spymicmac.micmac.clean_homol(img_pattern='OIS*.tif', dir_homol='Homol', min_size=None, remove_asymmetric=False, return_df=False)[source]#

Remove spurious homologue files based on a threshold file size.

Parameters:

  • img_pattern (str) – the image pattern to pass to glob to get a list of filenames

  • dir_homol (str) – the directory where the homologue files are

  • min_size (int | None) – the size, in bytes, to use as a threshold for removing file (default: calculated from all files)

  • remove_asymmetric (bool) – remove asymmetric homologue files (pairs where only one image in the pair “sees” the other one)

  • return_df (bool) – return a DataFrame of all homologue files, rather than removing them

Returns:

a DataFrame of homologue files and associated information

Return type:

None | DataFrame

spymicmac.micmac.find_empty_homol(imlist=None, dir_homol='Homol', pattern='OIS*.tif')[source]#

Search through a Homol directory to find images without any matches, then move them to a new directory called ‘EmptyMatch’

Parameters:

  • imlist (list | None) – a list of images in the current directory. If None, uses pattern to find images.

  • dir_homol (str) – the Homol directory to search in

  • pattern (str) – the search pattern to use to find images

Return type:

None

spymicmac.micmac.find_connected_blocks(pattern='OIS*.tif', dir_homol='Homol')[source]#

Find connected blocks of images.

Parameters:

  • pattern (str) – the search pattern to use to get image names

  • dir_homol (str | Path) – the Homologue directory to use to determine what images are connected

Returns:

blocks – a list containing lists of connected blocks of images

Return type:

list

spymicmac.micmac.separate_blocks(pattern='OIS*.tif', dir_homol='Homol', min_size=2)[source]#

Based on homologous points, find connected blocks of images and then separate the files into sub-folders. Moves files from {dir_homol} and Pastis, along with the image files.

Parameters:

  • pattern (str) – the search pattern to use to get image names

  • dir_homol (str | Path) – the Homologue directory to use to determine what images are connected

  • min_size (int) – the minimum number of images to be considered a block

Return type:

None

spymicmac.micmac.pairs_from_homol(img_pattern='OIS*.tif', dir_homol='Homol')[source]#

Get a list of image pairs based on homologue files.

Parameters:

  • img_pattern (str) – the image pattern to pass to glob to get a list of filenames

  • dir_homol (str) – the directory where the homologue files are

Returns:

pairs – a list of tuples representing image pairs

Return type:

list

measures files#

These methods are used for working with various Measures XML files.

spymicmac.micmac.parse_im_meas(fn_meas)[source]#

Read an xml file with image locations into a pandas DataFrame.

Parameters:

fn_meas (str | Path) – the name of the measures file to read.

Returns:

gcp_df – a DataFrame with gcp names and image locations.

Return type:

DataFrame

spymicmac.micmac.remove_measure(fn_meas, name)[source]#

Remove all instances of a given measure from an xml file.

Parameters:

  • fn_meas (str | Path) – the xml file (e.g., AutoMeasures-S2D.xml)

  • name (str) – the measurement name (e.g., GCP0)

Return type:

None

spymicmac.micmac.remove_worst_mesures(fn_meas, ori)[source]#

Remove outlier measures from an xml file, given the output from Campari.

Parameters:

  • fn_meas (str | Path) – the filename for the measures file.

  • ori (str) – the orientation directory output from Campari (e.g., Ori-TerrainFinal -> TerrainFinal)

Return type:

None

camera xml files#

spymicmac.micmac.load_cam_xml(fn_cam)[source]#

Parse an AutoCal xml file into a dictionary of intrinsic parameters.

  • pp: the principal point of the camera, in image coordinates

  • focal: the focal length of the camera

  • size: the size of the image (width height)

  • cdist: the image coordinates of the center of distortion

  • K*: the coefficients for the radial component of the distortion model, K1, K2, K3, etc.

If the camera model used has both affine and decentric distortion parameters, these will also be included as [P1, P2] for the affine and [b1, b2] for the decentric distortion, respectively.

Currently tested/working on outputs from Tapas Radial[Basic, Std, Extended] and Fraser[Basic].

Parameters:

fn_cam (str | Path) – the name of the AutoCal xml file to parse.

Returns:

cam_dict – a dictionary of intrinsic parameter values for the camera

Return type:

dict

spymicmac.micmac.write_cam_xml(fn_xml, cam_dict, fraser=True)[source]#

Write a camera xml file.

Parameters:

  • fn_xml (str | Path) – the name of the xml file to write

  • cam_dict (dict) – a dictionary containing camera parameters, as read by micmac.load_cam_xml()

  • fraser (bool) – whether to add decentric and affine parameters to the xml

Return type:

None

version control#

In case you wish to keep track of changes to the various XML files created by MicMac, especially the camera calibration and orientation files, the following method will initialize an empty git repository in the current directory, and populate the .gitignore file with common patterns to ignore (e.g., *.tif).

spymicmac.micmac.init_git()[source]#

Initialize a git repository in the current working directory.

Return type:

None