1================================================================================
2PDAL
3================================================================================
4
5PDAL Python support allows you to process data with PDAL into `Numpy`_ arrays.
6It supports embedding Python in PDAL pipelines with the `readers.numpy
7<https://pdal.io/stages/readers.numpy.html>`__ and `filters.python
8<https://pdal.io/stages/filters.python.html>`__ stages, and it provides a PDAL
9extension module to control Python interaction with PDAL.
10
11Additionally, you can use it to fetch `schema`_ and `metadata`_ from
12PDAL operations.
13
14Installation
15--------------------------------------------------------------------------------
16
17PyPI
18................................................................................
19
20PDAL Python support is installable via PyPI:
21
22.. code-block::
23
24 pip install PDAL
25
26GitHub
27................................................................................
28
29The repository for PDAL's Python extension is available at https://github.com/PDAL/python
30
31Python support released independently from PDAL itself as of PDAL 1.7.
32
33Usage
34--------------------------------------------------------------------------------
35
36Simple
37................................................................................
38
39Given the following pipeline, which simply reads an `ASPRS LAS`_ file and
40sorts it by the ``X`` dimension:
41
42.. _`ASPRS LAS`: https://www.asprs.org/committee-general/laser-las-file-format-exchange-activities.html
43
44.. code-block:: python
45
46
47 json = """
48 {
49 "pipeline": [
50 "1.2-with-color.las",
51 {
52 "type": "filters.sort",
53 "dimension": "X"
54 }
55 ]
56 }"""
57
58 import pdal
59 pipeline = pdal.Pipeline(json)
60 count = pipeline.execute()
61 arrays = pipeline.arrays
62 metadata = pipeline.metadata
63 log = pipeline.log
64
65Reading using Numpy Arrays
66................................................................................
67
68The following more complex scenario demonstrates the full cycling between
69PDAL and Python:
70
71* Read a small testfile from GitHub into a Numpy array
72* Filters those arrays with Numpy for Intensity
73* Pass the filtered array to PDAL to be filtered again
74* Write the filtered array to an LAS file.
75
76.. code-block:: python
77
78 data = "https://github.com/PDAL/PDAL/blob/master/test/data/las/1.2-with-color.las?raw=true"
79
80
81 json = """
82 {
83 "pipeline": [
84 {
85 "type": "readers.las",
86 "filename": "%s"
87 }
88 ]
89 }"""
90
91 import pdal
92 import numpy as np
93 pipeline = pdal.Pipeline(json % data)
94 count = pipeline.execute()
95
96 # get the data from the first array
97 # [array([(637012.24, 849028.31, 431.66, 143, 1,
98 # 1, 1, 0, 1, -9., 132, 7326, 245380.78254963, 68, 77, 88),
99 # dtype=[('X', '<f8'), ('Y', '<f8'), ('Z', '<f8'), ('Intensity', '<u2'),
100 # ('ReturnNumber', 'u1'), ('NumberOfReturns', 'u1'), ('ScanDirectionFlag', 'u1'),
101 # ('EdgeOfFlightLine', 'u1'), ('Classification', 'u1'), ('ScanAngleRank', '<f4'),
102 # ('UserData', 'u1'), ('PointSourceId', '<u2'),
103 # ('GpsTime', '<f8'), ('Red', '<u2'), ('Green', '<u2'), ('Blue', '<u2')])
104
105 arr = pipeline.arrays[0]
106 print (len(arr)) # 1065 points
107
108
109 # Filter out entries that have intensity < 50
110 intensity = arr[arr['Intensity'] > 30]
111 print (len(intensity)) # 704 points
112
113
114 # Now use pdal to clamp points that have intensity
115 # 100 <= v < 300, and there are 387
116 clamp =u"""{
117 "pipeline":[
118 {
119 "type":"filters.range",
120 "limits":"Intensity[100:300)"
121 }
122 ]
123 }"""
124
125 p = pdal.Pipeline(clamp, [intensity])
126 count = p.execute()
127 clamped = p.arrays[0]
128 print (count)
129
130 # Write our intensity data to an LAS file
131 output =u"""{
132 "pipeline":[
133 {
134 "type":"writers.las",
135 "filename":"clamped.las",
136 "offset_x":"auto",
137 "offset_y":"auto",
138 "offset_z":"auto",
139 "scale_x":0.01,
140 "scale_y":0.01,
141 "scale_z":0.01
142 }
143 ]
144 }"""
145
146 p = pdal.Pipeline(output, [clamped])
147 count = p.execute()
148 print (count)
149
150
151
152
153.. _`Numpy`: http://www.numpy.org/
154.. _`schema`: http://www.pdal.io/dimensions.html
155.. _`metadata`: http://www.pdal.io/development/metadata.html
156
157.. image:: https://github.com/PDAL/python/workflows/Build/badge.svg
158 :target: https://github.com/PDAL/python/actions?query=workflow%3ABuild
159
160Requirements
161================================================================================
162
163* PDAL 2.2+
164* Python >=3.6
165* Cython (eg :code:`pip install cython`)
166* Packaging (eg :code:`pip install packaging`)
167* scikit-build (eg :code:`pip install scikit-build`)
168
169
