157 |
159 |
160 |
161 |
155 |
156 |
162 |
163 | 
3 | pyfor
4 | Documentation | 5 | Changelog | 6 | Request a Feature | 7 | Road Map 8 |
9 |
11 |
2 |
3 | pyfor
4 | Documentation |
5 | Changelog |
6 | Request a Feature |
7 | Road Map
8 |
9 |
10 |
11 |
The key to an advanced usage of pyfor is understanding the base classes of the package. A full 159 | understanding of these allows for flexible and creative ways of conducting your processing task. 160 | This document outlines these classes in a qualitative way. See the documentation for particulars.
161 |pyfor.clip.poly_clip(points, poly)¶Returns the indices of points that are within a given polygon. This differs from ray_trace() in that it enforces a small “pre-clip” optimization by first clipping to the polygon bounding box. This function is directly called by Cloud.clip().
cloud – A cloud object.
poly – A shapely Polygon, with coordinates in the same CRS as the point cloud.
A 1D numpy array of indices corresponding to points within the given polygon.
177 |pyfor.clip.ray_trace(x, y, poly)¶Determines for some set of x and y coordinates, which of those coordinates is within poly. Ray trace is generally called as an internal function, see poly_clip()
x – A 1D numpy array of x coordinates.
y – A 1D numpy array of y coordinates.
poly – The coordinates of a polygon as a numpy array (i.e. from geo_json[‘coordinates’]
A 1D boolean numpy array, true values are those points that are within poly.
195 |pyfor.clip.square_clip(points, bounds)¶Clips a square from a tuple describing the position of the square.
203 |points – A N x 2 numpy array of x and y coordinates, where x is in column 0
bounds – A tuple of length 4, min y and max y coordinates of the square.
A boolean mask, true is within the square, false is outside of the square.
212 |pyfor.gisexport.array_to_raster(array, affine, crs, path)¶Writes a GeoTIFF raster from a numpy array.
168 |array – 2D numpy array of cell values
affine – The affine transformation.
crs – A rasterio-compatible coordinate reference (e.g. a proj4 string)
path – The output bath of the GeoTIFF
pyfor.gisexport.project_indices(indices, raster)¶Converts indices of an array (for example, those indices that describe the location of a local maxima) to the 184 | same space as the input cloud object.
185 |indices – The indices to project, an Nx2 matrix of indices where the first column are the rows (Y) and
188 |the second column is the columns (X) 191 | :param raster: An object of type pyfor.rasterizer.Raster 192 | :return:
193 |pyfor.voxelizer.VoxelGrid(cloud, cell_size)¶Bases: object
A 3 dimensional grid representation of a point cloud. This is analagous to the rasterizer.Grid class, but 168 | with three axes instead of two. VoxelGrids are generally used to produce VoxelRaster objects.
169 |__init__(cloud, cell_size)¶Initialize self. See help(type(self)) for accurate signature.
173 |voxel_raster(func, dim)¶Creates a 3 dimensional voxel raster, analagous to rasterizer.Grid.raster.
179 |func – The function to summarize within each voxel.
dim – The dimension upon which to summarize (i.e. “z”, “intensity”, etc.)
miniconda or Anaconda is required for your system before beginning. pyfor depends on many 161 | packages that are otherwise tricky and difficult to install (especially gdal and its bindings), 162 | and conda provides a quick and easy way to manage many different Python environments on your 163 | system simultaneously.
164 |The following bash commands will install this branch of pyfor. It requires installation of miniconda (see above). This will install all of the prerequisites in that environment, named pyfor_env. pyfor depends on a lot of heavy libraries, so expect construction of the environment to take a little time.
165 |git clone https://github.com/brycefrank/pyfor.git
166 | cd pyfor
167 | conda env create -f environment.yml
168 |
169 | # For Linux / macOS:
170 | source activate pyfor_env
171 |
172 | # For Windows:
173 | activate pyfor_env
174 |
175 | pip install .
176 | Following these commands, pyfor should load in an activated Python shell:
179 |import pyfor
180 | If you see no errors, you are ready to process.
183 || 165 | p | ||
| 169 | |
170 | pyfor | 171 | |
| 174 | |
175 | pyfor.clip | 176 | |
| 179 | |
180 | pyfor.cloud | 181 | |
| 184 | |
185 | pyfor.collection | 186 | |
| 189 | |
190 | pyfor.gisexport | 191 | |
| 194 | |
195 | pyfor.ground_filter | 196 | |
| 199 | |
200 | pyfor.metrics | 201 | |
| 204 | |
205 | pyfor.rasterizer | 206 | |
| 209 | |
210 | pyfor.voxelizer | 211 | |
This document provides an in-depth discussion of the structure of pyfor.
159 |pyfor is unique from other forest inventory LiDAR processing packages in that it is built on top of an object oriented (OOP) framework. Python is not stricly an OOP programming language, but allows for its implementation in a flexible way. pyfor takes advantage of this attractive feature of Python to offer a natural way of thinking about LiDAR as a collection of objects. Each object flows into the other through the process of LiDAR data analysis. Using pyfor means being comfortable with this framework and knowledgeable about what each of the following objects can do. This document is a primer on grasping this philosophy.
163 |There are four main classes that define pyfor. They are:
164 |Cloud
CloudDataFrame
Grid
Raster
The Cloud class represents the point cloud data in its raw format, a list of x, y and z coordinates (and some other fields like intensity and the like). The Cloud object can be plotted in a variety of ways, including 2D and 3D plots (see .plot, .plot3d, .iplot3d). The Cloud is generally considered the starting point of LiDAR analysis, from this object we can produce other objects, specifically the Raster and Grid.
173 |The Grid can be considered the next step in producing products from our Cloud. The Grid assigns each point of the Cloud to a grid cell. This process allows us to summarize information about the points in each grid cell.
177 |Once we have decided how to summarize our grid cells, we produce a Raster. The Raster is a geo-referenced numpy array where the value of each cell is some summarization of the points within that cell. The most common implementation of a Raster is the canopy height model (CHM) that is a summary of the highest points within each grid cell, but other types are possible, such as bare earth models (BEM) and grid metrics. We can write Rasters to a GeoTIFF format using Raster.write().
181 |At some point we will want to interact with our LiDAR tiles in toto. CloudDataFrame is a collection of Cloud objects that allows for efficient analysis and manupulation of many Cloud objects. Because Cloud is considered the most base of all classes in pyfor, CloudDataFrame is our portal to all the products we desire on a mass scale.
185 |Often times we want to clip out LiDAR points using a shapefile. This can be done using pyfor’s 169 | Cloud.clip method. pyfor integrates with geopandas and shapely, convenient geospatial packages 170 | for Python, to provide a way to clip point clouds.
171 |
import pyfor
172 | import geopandas
173 |
174 | # Load point cloud
175 | pc = pyfor.cloud.Cloud("../data/test.las")
176 | pc.plot3d()
177 | 
180 | As input to the clipping function we need any shapely.geometry.Polygon our heart desires, as 181 | long as its coordinates correspond to the same physical space as the Cloud object. Here I extract 182 | a Polygon from a shapefile using geopandas:
183 |# Load point cloud
184 | polys = geopandas.read_file("../data/clip.shp")
185 | poly = poly_frame["geometry"].iloc[0]
186 | Finally, pass the Polygon to the clipping function. This function returns a new Cloud object.
189 |# Load point cloud
190 | clipped = pc.clip(poly)
191 | clipped.plot3d()
192 | 
195 | One of the most integral parts of LiDAR analysis is determining which points represent 169 | the ground. Once this step is completed, we can construct bare earth models (BEMs) and 170 | normalize our point clouds to produce reliable estimates of height, canopy height models 171 | and other products.
172 |pyfor offers a few avenues for normalization, ground filtering and the creation of bare earth 173 | models. All of these methods are covered in the advanced Ground Filtering document. Here, only 174 | the convenience wrapper is covered.
175 |The convenience wrapper Cloud.normalize is a function that filters the cloud object for ground 176 | points, creates a bare earth model, and uses this bare earth model to normalize the object in 177 | place. That is, it conducts the entire normalization process from the raw data and does not 178 | leverage existing classified ground points. See the advanced Ground Filtering document to use 179 | existing classified ground points.
180 |It uses the Zhang2003 filter by default and takes as its first argument the resolution 181 | of the bare earth model:
182 |import pyfor
183 | tile = pyfor.cloud.Cloud('my_tile.las')
184 | tile.normalize(1)
185 |