spymicmac.micmac

spymicmac.micmac is a collection of tools for interfacing with MicMac

spymicmac.micmac.dem_to_text(fn_dem, fn_out='dem_pts.txt', spacing=100)

Write elevations from a DEM raster to a text file for use in mm3d PostProc Banana.

Parameters

• fn_dem (str) – the filename of the DEM to read.

• fn_out (str) – the name of the text file to write out (default: dem_pts.txt)

• spacing (int) – the pixel spacing of the DEM to write (default: every 100 pixels)

spymicmac.micmac.extend_line(df, first, last)

Extend a flightline using existing camera positions.

Parameters

• df (GeoDataFrame) – a GeoDataFrame containing the camera positions and image names

• first (str) – the name of the image to start interpolating from.

• last (str) – the name of the image to end interpolating at.

Returns

• outpt (shapely.Point) – the new point along the flightline.

spymicmac.micmac.fix_orientation(cameras, ori_df, ori, nsig=4)

Correct erroneous Tapas camera positions using an estimated affine transformation between the absolute camera locations and the relative locations read from the orientation directory.

Once the positions have been updated, you should re-run Tapas using the InOri set to the directory; e.g., if you have updated Ori-Relative, you should run:

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

Parameters

• cameras (pandas.DataFrame) – A DataFrame containing camera positions (x, y, z) and a ‘name’ column that contains the image names.

• ori_df (pandas.DataFrame) – A DataFrame output from sPyMicMac.micmac.load_all_orientations, or that contains a ‘name’ column and camera positions in relative space (x, y, z)

• ori (str) – the Orientation directory to update (e.g., Ori-Relative)

• nsig (int|float) – the number of normalized absolute deviations from the median residual value to consider a camera an outlier (default: 4)

spymicmac.micmac.generate_measures_files(joined=False)

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

Parameters

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

spymicmac.micmac.get_bascule_residuals(fn_basc, gcp_df)

Read a given GCPBascule residual file, and add the residuals to a DataFrame with GCP information.

Parameters

• fn_basc (str) – the GCPBascule xml file to read the residuals from.

• gcp_df (pandas.DataFrame) – a DataFrame with the GCPs to read the residuals for.

Returns

• gcp_df (pandas.DataFrame) – the input GCPs with the Bascule residuals added.

spymicmac.micmac.get_campari_residuals(fn_resids, gcp_df)

Read a given Campari residual file, and add the residuals to a DataFrame with GCP information.

Parameters

• fn_resids – the Campari residual xml file to read.

• gcp_df (pandas.DataFrame) – a DataFrame with the GCPs to read the residuals for.

Returns

• gcp_df (pandas.DataFrame) – the input GCPs with the Campari residuals added.

spymicmac.micmac.get_gcp_meas(im_name, meas_name, in_dir, E, nodist=None, gcp_name='GCP')

Create an lxml.builder.ElementMaker object with a GCP name and the image (row, pixel) location.

Parameters

• im_name (str) – the image name to write the GCP location for.

• meas_name (str) – the name of the file to read the point locations from.

• in_dir (str) – the name of the directory where the images and measures files are located.

• E (lxml.builder.ElementMaker) – an ElementMaker object for writing to the xml file.

• nodist (str) – the name of the directory

• gcp_name (str) – the prefix (e.g., GCP0, GCP1, etc.) for the GCP name (default: GCP).

Returns

• this_im_meas (lxml.builder.ElementMaker) – an ElementMaker object with the GCP location in the image.

spymicmac.micmac.get_im_meas(gcps, E)

Populate an lxml.builder.ElementMaker object with GCP image locations, for writing to xml files.

Parameters

• gcps (pandas.DataFrame) – a DataFrame with the GCPs to find image locations for.

• E (lxml.builder.ElementMaker) – an ElementMaker object for writing to the xml file.

Returns

• pt_els (list) – a list of ElementMaker objects corresponding to each GCP image location.

spymicmac.micmac.get_match_pattern(imlist)

Given a list of image names, return a match pattern that can be passed to MicMac command line functions.

Parameters

imlist (list) – a list of image names.

Returns

• pattern (str) – a match pattern (e.g., “OIS.*tif”) that can be passed to MicMac functions.

spymicmac.micmac.get_valid_image_points(shape, pts, pts_nodist)

Find which image points are located within an image based on the size of the image.

Parameters

• shape – the shape of the image (rows, columns) to determine valid points for.

• pts (pandas.DataFrame) – a DataFrame containing point locations (i, j)

• pts_nodist (pandas.DataFrame) – a DataFrame containing point locations (i, j) calculated using no camera distortion.

Returns

• valid_pts (array-like) – an array of the points that are located within the image shape.

spymicmac.micmac.interp_line(df, first, last, nimgs=None, pos=None)

Interpolate camera positions along a flightline.

Parameters

• df (GeoDataFrame) – a GeoDataFrame containing the camera positions and image names

• first (str) – the name of the image to start interpolating from.

• last (str) – the name of the image to end interpolating at.

• nimgs (int) – the number of images to interpolate (default: calculated based on the image numbers)

• pos (int) – which image position to return (default: all images between first and last)

Returns

• ptList (list) – a list containing the interpolated camera positions (or, a tuple of the requested position).

spymicmac.micmac.load_all_orientation(ori, imlist=None)

Load all of the orientation parameters for a set of images from a given directory.

Parameters

• ori (str) – the orientation directory to read

• imlist (list) – the images to load. If not set, loads all orientation files from the given directory.

Returns

• df (pandas.DataFrame) – a DataFrame containing the orientation parameters for each image

spymicmac.micmac.load_orientation(fn_img, ori)

Read camera position and rotation information from an Orientation xml file.

Parameters

• fn_img (str) – the name of the image to read the orientation file for.

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

Returns

• centre (list) – the camera position (x, y, z)

• l1 (list) – the L1 orientation parameters

• l2 (list) – the L2 orientation parameters

• l3 (list) – the L3 orientation parameters

• prof (float) – the ‘Profondeur’ value from the xml file.

• altisol (float) – the ‘AltiSol’ value from the xml file.

spymicmac.micmac.move_bad_tapas(ori)

Read residual files output from Tapas (or Campari, GCPBascule), and move images with a NaN residual.

Parameters

ori (str) – the orientation directory to read the residuals file from (e.g., ‘Ori-Relative’).

spymicmac.micmac.parse_im_meas(fn_meas)

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

Parameters

fn_meas – the name of the measures file to read.

Returns

• gcp_df (pandas.DataFrame) – a DataFrame with gcp names and image locations.

spymicmac.micmac.remove_measure(fn_meas, name)

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

Parameters

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

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

spymicmac.micmac.run_bascule(in_gcps, outdir, img_pattern, sub, ori)

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

Parameters

• in_gcps (pandas.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).

Returns

• out_gcps (pandas.DataFrame) – the input gcps with the updated Campari residuals.

spymicmac.micmac.run_campari(in_gcps, outdir, img_pattern, sub, dx, ortho_res, allfree=True)

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

Parameters

• in_gcps (pandas.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) – the pixel resolution of the reference image.

• ortho_res (int|float) – the pixel resolution of the orthoimage being used.

• allfree (bool) – run Campari with AllFree=1 (True), or AllFree=0 (False). (default: True)

Returns

• out_gcps (pandas.DataFrame) – the input gcps with the updated Campari residuals.

spymicmac.micmac.save_gcps(in_gcps, outdir, utmstr, sub)

Save a GeoDataFrame of GCP information to shapefile, txt, and xml formats.

After running, the following new files will be created:

• outdir/AutoGCPs.shp (+ associated files)

• outdir/AutoGCPs.txt

• outdir/AutoGCPs.xml (output from mm3d GCPConvert)

• outdir/AutoMeasures.xml (a file with image locations for each GCP)

Parameters

• in_gcps (GeoDataFrame) – the gcps GeoDataFrame to save

• outdir (str) – the output directory to save the files to

• utmstr (str) – a UTM string generated by register.get_utm_str()

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

spymicmac.micmac.update_center(fn_img, ori, new_center)

Update the camera position in an Orientation file.

Parameters

• fn_img (str) – the name of the image to update the orientation for (e.g., ‘OIS-Reech_ARCSEA000590122.tif’)

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

• new_center (list) – a list of the new camera position [x, y, z]

spymicmac.micmac.write_auto_gcps(gcp_df, sub, outdir, utm_zone, outname='AutoGCPs')

Write GCP name, x, y, and z information to a text file to use with mm3d GCPConvert.

Parameters

• gcp_df (pandas.DataFrame) – a DataFrame with the GCPs to save.

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

• outdir (str) – the output directory to save the files to.

• utm_zone (str) – the UTM zone name (e.g., 8N).

• outname (str) – the name to use for the GCPs file (default: AutoGCPs.txt)

spymicmac.micmac.write_auto_mesures(gcps, sub, outdir, outname='AutoMeasures')

Write a file with GCP locations in relaive space (x, y, z) to use with get_autogcp_locations.sh

Parameters

• gcps (pandas.DataFrame) – a DataFrame with the GCPs to save.

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

• outdir (str) – the output directory to save the files to.

• outname (str) – the base name of the file to create (default: AutoMeasures).

spymicmac.micmac.write_image_mesures(imlist, gcps, outdir='.', sub='', ort_dir='Ortho-MEC-Relative')

Create a Measures-S2D.xml file (row, pixel) for each GCP in each image from a list of image names.

Parameters

• imlist (list) – a list of image names.

• gcps (pandas.DataFrame) – a DataFrame of GCPs.

• outdir (str) – the output directory to save the files to.

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

• ort_dir (str) – the Ortho-MEC directory where the images are located.

spymicmac.micmac.write_neighbour_images(imlist, fprints=None, nameField='ID', prefix='OIS-Reech_', fileExt='.tif', dataset='AERIAL_COMBIN')

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_’)

• fprints (GeoDataFrame) – a vector dataset of footprint polygons. If not provided, will attempt to download metadata from USGS for the images.

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

• prefix (str) – the prefix attached to the image name read by Tapioca (default: ‘OIS-Reech_’)

• fileExt (str) – the file extension for the images read by Tapioca (default: .tif)

• dataset – the USGS dataset name to search if no footprints are provided (default: AERIAL_COMBIN)