Ecosynth 0.2.4 documentation

Post-Process and Analysis (Stage 3)

«  Point Cloud Generation (Stage 2)   ::   Contents

Post-Process and Analysis (Stage 3)

The Post-Processing and Analysis module contains tools for filtering and georeferencing the Point Clouds that have been generated by SfM Computer Vision programs.

Post-Process Pipelines

postprocess.run.standard_pipeline(out_file, log_file, msl_float, outputs_filepath=None, cams_geo_file=None, ply_file=None, points_txt_file=None, gps_file=None, logger_file=None, ecobrowser_ply_file=None, dense_ply_file_in=None, dense_ply_file_out=None, helm_params_file=None)

Entry point for Post-Processing stage of automated pipeline

Parameters:
  • out_file (file) – Bundler OUT file
  • log_file (file) – LOG file from Acquisition stage
  • msl_float (float) – lauch altitude (meters above mean sea level)
  • cams_geo_file – (Optional) Clean file to write georeferenced cameras
  • ply_file (file) – (Optional) Clean file to write georeferenced and noise-filtered PLY
  • points_txt_file (file) – (Optional) Clean file to write georeferenced and noise-filtered points
  • gps_file (file) – (Optional) Clean file to write GPS positions
  • logger_file (file) – (Optional) File currently for debugging and point cloud statistics
  • ecobrowser_ply_file (file) – (Optional) PLY file with extra info for web-viewable point cloud
  • dense_ply_file_in (file) – (Optional) Dense PLY File to Transform
  • dense_ply_file_out (file) – (Optional) Transformed Dense PLY File
  • helm_params_file (file) – (Optional) Clean file to write Helmert parameters
Returns:

cr_object (of dense cloud when dense_ply_files present, else of sparse)

Return type:

CloudRasterizer

IO

postprocess.io.load_out(out_file)
Parameters:out_file (file) – Bundler OUT file
Returns:out_tuple
Return type:Named Tuple
Example
>>> f = open(out_file, ‘r’)
>>> out_tuple = postprocess.io.load_out(f)

Out Tuple Contents:
out_tuple.cameras_total <integer>
out_tuple.cameras_used <integer>
out_tuple.cam_array (Unknown Format) <numpy array>
out_tuple.cam_array_fixed (Unknown Format) <numpy array>
used cameras correctly ordered and
eliminates unused cameras
out_tuple.points_total <integer>
out_tuple.xyzrgb_array <numpy array>
out_tuple.xyzrgbCXY_array <numpy array>

Notes
See here to learn more about the OUT file Format
postprocess.io.load_ply(ply_file, delim=' ')

Reads in PLY file and returns a PointCloud object

Parameters:
  • ply_file (file) – PLY-formatted ascii file
  • delim (string) – (Optional) delimiter for coordinate dimensions
Returns:

ply_tuple

Return type:

Named Tuple

PLY Tuple Contents:
ply_tuple.header <string>
ply_tuple.points_total <integer>
ply_tuple.xyzrgb_array <numpy array>

Example
>>> f = open(filepath, ‘r’)
>>> ply_tuple = postprocess.io.load_ply(f)

postprocess.io.save_ply(ply_file, xyzrgb_array)

Saves a PLY named tuple as a PLY file

Parameters:
  • ply_file (file) – file to save PLY formatted data
  • xyzrgb_array (np.array) – PLY XYZRGB array
Notes
- Currently assumes the number of points in the file has not been
changed since the PLY was loaded
- Currently saves all XYZRGB values to %.18e (–> larger file size)
- Future: Add support for creating PLY files from tuples without headers
Example
f = open(filepath, ‘w’)
postprocess.io.save_ply(f, xyzrgb_array)
f.close()
postprocess.io.ply_to_ecobrowser_point_cloud()

This is a potential function

Parameters:
  • a (str) – A string to be converted
  • v (integ) – A string to be converted
  • b (type) – optional parameter
Returns:

the return

Return type:

int

Raises IndexError:
 

if such and such

Notes
here
Example
here
postprocess.io.plot3Darray(array3D, filepath)

Plots a three-dimensional array and saves the figure

Parameters:
  • array3D (np.array) –
  • filepath (string) – absolute or relative filepath
postprocess.io.save_ascii_raster(raster_file, raster, xllcorner, yllcorner, cellsize=1, NODATA_value=-9999, fmt='%0.5f')

Saves an MxN numpy array in ESRI Ascii Raster format

Parameters:
  • raster_file (file) –
  • raster (np.array) –
  • xllcorner (float) –
  • yllcorner (float) –
  • cellsize (float) – (Optional)
  • NODATA_value (int) – (Optional)
  • fmt (string) – (Optional)
Notes
Assumes inputted raster’s NODATA values are None-type
Output Raster File
- Space-delimited cells
Example
>>> raster = cr_object.get_mean_height_raster()
>>> aoi = cr_object.get_aoi()
>>> raster_file = open(raster_filepath, ‘w’)
>>> save_ascii_raster(raster_file, raster, aoi[0], aoi[1])
>>> raster_file.close()
postprocess.io.save_image(image_filepath, color_raster, aoi)

Saves an MxNx3 numpy array as an image in the format specified by the extension of the image_file (TIFF, JPG, PNG, etc.)

Parameters:
  • image_filepath (string) –
  • color_raster (np.array) –
  • aoi (list) – [eastMin, eastMax, northMin, northMax, elevMin, elevMax]
Notes

Output Raster File

Example
>>> color_raster = cr_object.get_color_raster()
>>> image_filepath = ‘path/to/file.tiff’
>>> save_image(image_filepath, color_raster)

Transforms

postprocess.transforms.georef_telemetry(out_tuple, gps_array, logger=None)

Produces a georeferenced xyzrgb_array using gps positions, the fmin_powell optimization algorithm, and the Helmert transform

Parameters:
  • out_tuple (tuple) – Bundler OUT named tuple
  • gps_array (np.array) – GPS positions ordered sequentially in time
  • logger (file) – (Optional) Clean file to write Optimization Error Info
Returns:

xyzrgb_array_transformed - georeferenced coordinates

Return type:

np.array

Returns:

parameters

Return type:

list [omega, phi, kappa, s, Tx, Ty, Tz]

Raises IndexError:
 

if such and such

Notes
here
Example
here
postprocess.transforms.georef_telemetry_file(out_file, gps_file, logger=None)

Produces a georeferenced xyzrgb_array using gps positions, the fmin_powell optimization algorithm, and the Helmert transform

Parameters:
  • out_file (file) – Bundler OUT file
  • gps_file (file) – Clean file to write GPS positions
  • logger (file) – (Optional) Clean file to write Optimization Error Info
Returns:

xyzrgb_array_transformed - georeferenced coordinates

Return type:

np.array

Returns:

parameters

Return type:

list [omega, phi, kappa, s, Tx, Ty, Tz]

Raises IndexError:
 

if such and such

Notes
here
Example
here
postprocess.transforms.apply_helmert(parameters, raw)

(NOTE: Check to make sure output array has correct shape) Applies Helmert transform to a coordinate array given a seven parameter array

Parameters:
  • parameters (list) – optimized parameters for helmert transform
  • raw (np.array) – coordinate array to be transformed
Returns:

transformed_array (x y z)

Return type:

np.array

Notes
here
Example
here
postprocess.transforms.georef_grnd_cntrl()

(NOTE: Unimplemented)

This is a one-sentence summary

Parameters:
  • a (str) – A string to be converted
  • v (integ) – A string to be converted
  • b (type) – optional parameter
Returns:

the return

Return type:

int

Raises IndexError:
 

if such and such

Notes
here
Example
here
class postprocess.CloudRasterizer.CloudRasterizer(xyzrgb_array, resolution=1)

CloudRasterizer Class for processing Point Cloud and enabling 2D analysis

Parameters:
  • xyzrgb_array (np.array) – XYZRGB numpy array
  • resolution (int) – (Optional) grid size relative to units of point cloud (assumed to be meters)
Pararm list aoi:
 

(Optional) [xMin, xMax, yMin, yMax, zMin, zMax]

Variables:
  • resolution (int) – grid size relative to units of point cloud
  • cloud_array (np.array) – points in given AOI
  • xMin (int) –
  • yMin (int) –
  • zMin (int) –
  • grid (np.array) – 2D grid of arrays filled with XYZRGB points
Notes
here
Example
here
cloud_to_grid(xyzrgb_array, resolution)

Sorts points into an XYZ grid and returns grid

Parameters:
  • xyzrgb_array (np.array) –
  • resolution (int) –
Returns:

grid

Return type:

np.array

filter_noise_z(z_score_cutoff_global=3, z_score_cutoff_local=3)

Filters height noise above and below a given number of z-scores

Filters points from a grid that have heights (z-dim) greater than the given number of standard deviations away from standard score. The filter is first applied over the cloud and then locally in z-columns with x and y dimensions equal to the grid resolution.

Parameters:
  • z_score_cutoff_global (float) – (Optional)
  • z_score_cutoff_local (float) – (Optional)
filter_points_above_height(raster)

(Unimplemented) Filters points in grid that are above the corresponding value in the given raster

Parameters:raster (np.array) – (Note: np.arry or list or ?)
Returns:cv_object
Return type:CloudRasterizer
filter_points_below_height(raster)

(Unimplemented) Filters points in grid that are below the corresponding value in the given raster

Parameters:raster (np.array) – (Note: np.arry or list or ?)
Returns:cv_object
Return type:CloudRasterizer
get_Q95_elevation_raster(percentile=95)

Returns XY raster containing the Q95 percentile z-value for each Z column with respect to elevation

Returns:q95_elevation_raster
Return type:np.array
get_aoi(xyzrgb_array=None)

Searches own point_cloud and returns boundary points in physical space

Returns:aoi
Return type:list of integers [eastMin, eastMax, northMin, northMax, elevMin, elevMax]
Example
[35321, 35357, 46542, 46987, 10, 50]
get_cell(x, y, z)

(Unimplemented) Fetches points of a given XYZ cell and returns as an array

Parameters:
  • x (int) – Easting index (Check on this)
  • y (int) – Northing index (Check on this)
  • z (int) – Height index
Returns:

cell_array

Return type:

np.array

get_cloud_array()

Returns a copy of the cloud_array, with the option of subsetting it

Returns:cloud_array
Return type:np.array
get_color_raster()

Returns XY raster containing the RGB value for the highest point in each Z column

Returns:color_raster
Return type:np.array
Example

get_cv_elevation_raster()

Returns XY raster containing coefficients of variation for each Z column with respect to elevation

Returns:cv_elevation_raster
Return type:np.array
get_cv_height_raster()

Returns XY raster containing coefficients of variation for each Z column with respect to height

Returns:cv_height_raster
Return type:np.array
get_height_range_raster()

Returns XY raster containing the difference between the highest point and the lowest point in each Z column

Returns:height_range_raster
Return type:np.array
get_log_density_raster()

(Unimplemented) (Future implementation: add layer selection) Returns XY raster of containing logarithmic point cloud density for each Z column

point_density * log(point_density)

Returns:log_density_raster
Return type:np.array
get_max_elevation_raster()

(Note: Distinction needed for height and elevation) Returns XY raster containing the maximum z-value for each Z column in terms of elevation

Returns:max_elevation_raster
Return type:np.array
get_max_height_raster()

(Note: Distinction needed for height and elevation) Returns XY raster containing the maximum z-value for each Z column in terms of height

Returns:max_height_raster
Return type:np.array
get_mean_elevation_raster()

(Note: Distinction needed for height and elevation) Returns XY raster containing the mean z-value for each Z column in terms of elevation

Returns:mean_elevation_raster
Return type:np.array
get_mean_height_raster()

(Note: Distinction needed for height and elevation) Returns XY raster containing the mean z-value for each Z column in terms of height

Returns:mean_height_raster
Return type:np.array
get_median_elevation_raster()

(Note: Distinction needed for height and elevation) Returns XY raster containing the median z-value for each Z column in terms of elevation

Returns:median_elevation_raster
Return type:np.array
get_median_height_raster()

(Note: Distinction needed for height and elevation) Returns XY raster containing the median z-value for each Z column in terms of height

Returns:median_height_raster
Return type:np.array
get_point_density_raster()

(Future implementation: add layer selection) Returns XY raster containing the point density for each Z column

Returns:point_density_raster
Return type:np.array
get_shape()

Returns grid shape

Returns:grid_shape (X, Y)
Return type:tuple of integers
Example
>>> shape = cv.get_shape()
>>> print shape
(10, 10)
get_std_raster()

(Future implementation: add layer selection)

Returns XY raster containing the standard deviation for each Z column in terms of elevation

Returns:std_raster
Return type:np.array
get_x_column(x, y)

(Unimplemented)

get_xy_plane(z_index, subset=None)

(Unimplemented) Returns a copy of an XY grid at a given index in the Z dimension

Parameters:
  • z_index (int) – height index
  • subset (list) – aoi [xMin, xMax, yMin, yMax, zMin, zMax]
Returns:

2D grid

Return type:

list

get_xyz_grid(aoi=None)

Returns a copy of an XYZ grid, with the option of subsetting it

Parameters:aoi (list) – [xMin, xMax, yMin, yMax, zMin, zMax]
Returns:2D grid
Return type:list
get_xyzrgb_array()

Returns a copy of the cloud_array, with the option of subsetting it

Returns:xyzrgb_array
Return type:np.array
get_xz_plane(subset=None)

(Unimplemented)

get_y_column(x, y)

(Unimplemented)

get_yz_plane(subset=None)

(Unimplemented)

get_z_column(x, y)

Fetches all cells at a given XY index and returns as a single array

Parameters:
  • x (int) – Index (Check on this)
  • y (int) – Index (Check on this)
Returns:

z_column_array

Return type:

np.array

grid_to_cloud()

Takes points from a grid and builds an array

Parameters:grid (list) –
Returns:cloud_array
Return type:np.array
is_in_grid_bounds(x, y, z)

Boolean function that checks whether a given set of indices falls within the grid bounds

Returns:in_grid_bounds
Return type:boolean (True or False)
plot_meshgrid(raster)

(Unimplemented) Generates 3D mesh of given raster

Parameters:raster (np.array) –
Returns:image
Return type:png?
plot_raster_colors(raster, title=None, png_file=None)

Plots color raster

Parameters:
  • raster (np.array) – Two-dimensional grid with each cell containing three values (RGB)
  • title (string) – (Optional title)
  • png_file (file) – (Optional) outputs image to file as pn
plot_raster_heatmap(raster, title=None, png_file=None)

Generates 2D heatmap of given 2D raster

Parameters:
  • raster (np.array) –
  • title (string) – (Optional title)
  • png_file (file) – (Optional) outputs image to file as png
set_z_column(x, y, z_column_array)

Creates a list of cells and replaces grid cells in z column with given x and y indices

Parameters:
  • x (int) –
  • y (int) –
  • z_column_array (np.array) –
subset_cloud_array(xyzrgb_array, aoi=None)

Filters points outside given Area of Interest

Parameters:
  • xyzrgb_array (np.array) –
  • aoi (list) – (Optional) [xMin, xMax, yMin, yMax, zMin, zMax]
Returns:

xyzrgb_array_filtered

Return type:

np.array

«  Point Cloud Generation (Stage 2)   ::   Contents