You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can find the latest documentation [here](https://fugro-oss.github.io/LasDatasets.jl/dev/)
6
+
You can find the latest documentation [here](https://fugro-oss.github.io/LASDatasets.jl/dev/)
7
7
8
8
A Julia package for reading and writing *LAS* data. *LAS* is a public file format for saving and loading 3D point cloud data, and its source repository can be found [here](https://github.com/ASPRSorg/LAS). This package currently supports *LAS* specifications 1.1-1.4 (see [here](https://www.asprs.org/wp-content/uploads/2019/03/LAS_1_4_r14.pdf) for the 1.4 spec.)
9
9
@@ -20,8 +20,8 @@ These instructions will get you a copy of the project up and running on your loc
@@ -33,7 +33,7 @@ you follow the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
33
33
34
34
## Versioning
35
35
36
-
We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/fugro-oss/LasDatasets.jl/tags).
36
+
We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/fugro-oss/LASDatasets.jl/tags).
Copy file name to clipboardExpand all lines: docs/src/header.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Header
2
2
3
-
Each *LAS* file starts with a block of header information that contains metadata for the whole file. *LasDatasets.jl* uses the `LasHeader` struct to wrap around this data and defines a user-friendly interface to modify certain aspects of it.
3
+
Each *LAS* file starts with a block of header information that contains metadata for the whole file. *LASDatasets.jl* uses the `LasHeader` struct to wrap around this data and defines a user-friendly interface to modify certain aspects of it.
Copy file name to clipboardExpand all lines: docs/src/index.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# LasDatasets.jl
1
+
# LASDatasets.jl
2
2
3
3
A Julia package for reading and writing *LAS* data. *LAS* is a public file format for saving and loading 3D point cloud data, and its source repository can be found [here](https://github.com/ASPRSorg/LAS). This package currently supports *LAS* specifications 1.1-1.4 (see [here](https://www.asprs.org/wp-content/uploads/2019/03/LAS_1_4_r14.pdf) for the 1.4 spec.)
Copy file name to clipboardExpand all lines: docs/src/interface.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,22 @@
1
1
# High-Level Interface
2
2
3
-
*LasDatasets.jl* provides a number of high-level functions to easily manipulate your *LAS* data.
3
+
*LASDatasets.jl* provides a number of high-level functions to easily manipulate your *LAS* data.
4
4
5
5
## *LAS* Datasets
6
6
7
-
A `LasDataset` is a wrapper around data from a *LAS* file that acts as an interface to read, write and modify your *LAS* data. In general, a *LAS* file will have the following contents:
7
+
A `LASDataset` is a wrapper around data from a *LAS* file that acts as an interface to read, write and modify your *LAS* data. In general, a *LAS* file will have the following contents:
8
8
* File Header: contains metadata about the file contents and byte layout
9
9
**VLRs*: Variable length records of data that appear before the point records
10
10
* User-defined bytes: Additional bytes included after the last *VLR* and before the first point record
11
11
**LAS* point records: data assigned to each point in the point cloud (following a specific format specified in the header)
12
12
**EVLRs* : Extended *VLRs* that come after the point records (allows larger data payloads)
13
13
14
-
These are contained in a `LasDataset` as follows
14
+
These are contained in a `LASDataset` as follows
15
15
```@docs; canonical = false
16
-
LasDataset
16
+
LASDataset
17
17
```
18
18
19
-
You can query the contents of your `LasDataset` by using the following functions:
19
+
You can query the contents of your `LASDataset` by using the following functions:
20
20
```@docs; canonical = false
21
21
get_header
22
22
get_pointcloud
@@ -26,7 +26,7 @@ get_user_defined_bytes
26
26
```
27
27
28
28
## Reading
29
-
To read the entire contents of a *LAS* or *LAZ* file, you can use the `load_las` function. This returns a `LasDataset` with all the properties listed above. You also have the option of only loading certain point fields.
29
+
To read the entire contents of a *LAS* or *LAZ* file, you can use the `load_las` function. This returns a `LASDataset` with all the properties listed above. You also have the option of only loading certain point fields.
30
30
31
31
```julia
32
32
# read the full dataset
@@ -54,7 +54,7 @@ load_vlrs
54
54
```
55
55
56
56
## Writing
57
-
You can write the contents of your `LasDataset` to a file by using the `save_las` function. Note that this takes either a `LasDataset` on its own or a tabular point cloud with *(E)VLRs* and user-defined bytes supplied separately.
57
+
You can write the contents of your `LASDataset` to a file by using the `save_las` function. Note that this takes either a `LASDataset` on its own or a tabular point cloud with *(E)VLRs* and user-defined bytes supplied separately.
Note that when you supply just the point cloud outside of a `LasDataset`, *LasDatasets.jl* will automatically construct the appropriate header for you so you don't need to worry about the specifics of appropriate point formats etc.
77
+
Note that when you supply just the point cloud outside of a `LASDataset`, *LASDatasets.jl* will automatically construct the appropriate header for you so you don't need to worry about the specifics of appropriate point formats etc.
78
78
79
79
## Modifying LAS Contents
80
-
You can modify point fields in your `LasDataset` by adding new columns or merging in values from an existing vector.
80
+
You can modify point fields in your `LASDataset` by adding new columns or merging in values from an existing vector.
Copy file name to clipboardExpand all lines: docs/src/internals.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,11 +2,11 @@
2
2
3
3
## Data Consistency
4
4
5
-
When creating a `LasDataset` or writing a tabular point cloud out to a file, we need to make sure that the header information we provide is consistent with that of the point cloud and any *VLRs* and user bytes. Internally, this is done using the function `make_consistent_header!`, which compares a `LasHeader` and some *LAS* data and makes sure the header has the appropriate data offsets, flags and other metadata. This will, for example, make sure that the numbers of points, *VLRs* and *EVLRs* are consistent with the data we've provided, so your `LasDataset` is guaranteed to be consistent.
5
+
When creating a `LASDataset` or writing a tabular point cloud out to a file, we need to make sure that the header information we provide is consistent with that of the point cloud and any *VLRs* and user bytes. Internally, this is done using the function `make_consistent_header!`, which compares a `LasHeader` and some *LAS* data and makes sure the header has the appropriate data offsets, flags and other metadata. This will, for example, make sure that the numbers of points, *VLRs* and *EVLRs* are consistent with the data we've provided, so your `LASDataset` is guaranteed to be consistent.
6
6
7
7
```@docs; canonical = false
8
-
LasDatasets.make_consistent_header!
9
-
LasDatasets.make_consistent_header
8
+
LASDatasets.make_consistent_header!
9
+
LASDatasets.make_consistent_header
10
10
```
11
11
12
12
## Third Party Packages
@@ -20,21 +20,21 @@ We also use [BufferedStreams.jl](https://github.com/JuliaIO/BufferedStreams.jl)
20
20
As outlined in the [User Fields Section](./user_fields.md), in order to offer full support of "extra point data" in our *LAS* files, we treat *LAS* point records as having a point, extra user fields and a set of undocumented bytes. Internally, however, this is broken up into 4 separate classes each implementing the `LasRecord` abstract type. These correspond to each combination of a point with/without user fields/undocumented bytes.
21
21
22
22
```@docs; canonical = false
23
-
LasDatasets.LasRecord
24
-
LasDatasets.PointRecord
25
-
LasDatasets.ExtendedPointRecord
26
-
LasDatasets.UndocPointRecord
27
-
LasDatasets.FullRecord
23
+
LASDatasets.LasRecord
24
+
LASDatasets.PointRecord
25
+
LASDatasets.ExtendedPointRecord
26
+
LASDatasets.UndocPointRecord
27
+
LASDatasets.FullRecord
28
28
```
29
29
30
30
This was done largely to increase performance of reading point records, since having one single type for point records would require more conditional checks to see if certain extra fields need to be read from a file which ends up congesting the read process. Instead, we use *Julia*'s multiple dispatch and define `Base.read` and `Base.write` methods for each record type and avoid these checks and also decrease the type inference time when reading these into a vector.
31
31
32
32
## Reading Points Iterator
33
33
34
-
When reading, we also wrap our IO stream in an iterator, `LasDatasets.ReadPointsIterator`, to reduce the overhead of reading point records sequentially. It turns out that calling `map(r -> r, iter)` where `iter` is a `LasDatasets.ReadPointsIterator` is much faster than calling `map(_ -> read(io, TRecord), 1:num_points)`
34
+
When reading, we also wrap our IO stream in an iterator, `LASDatasets.ReadPointsIterator`, to reduce the overhead of reading point records sequentially. It turns out that calling `map(r -> r, iter)` where `iter` is a `LASDatasets.ReadPointsIterator` is much faster than calling `map(_ -> read(io, TRecord), 1:num_points)`
35
35
36
36
```@docs; canonical = false
37
-
LasDatasets.ReadPointsIterator
37
+
LASDatasets.ReadPointsIterator
38
38
```
39
39
40
40
## Writing Optimisations
@@ -43,12 +43,12 @@ Typically, *Julia* is slower at performing multiple consecutive smaller writes t
43
43
* How many user fields in this record and their data size in bytes and
44
44
* How many undocumented bytes there are.
45
45
46
-
This is done using `LasDatasets.get_record_bytes`, which takes a collection of *LAS* records and writes each *LAS* field, user field and extra bytes collection into its correct location in the final byte vector.
46
+
This is done using `LASDatasets.get_record_bytes`, which takes a collection of *LAS* records and writes each *LAS* field, user field and extra bytes collection into its correct location in the final byte vector.
47
47
48
48
In order to do this, we need to frequently access each field in a (potentially huge) list of records, which in normal circumstances is slow. We instead first pass our records into a `StructVector` using [StructArrays.jl](https://github.com/JuliaArrays/StructArrays.jl) which vastly increases the speed at which we can access these fields and broadcast over them.
49
49
50
50
```@docs; canonical = false
51
-
LasDatasets.get_record_bytes
51
+
LASDatasets.get_record_bytes
52
52
```
53
53
54
54
## Automatic Support for User Fields
@@ -57,6 +57,6 @@ In order for the system to automatically handle a user supplying their own custo
57
57
58
58
Firstly, the *LAS* 1.4 spec officially supports the following data types directly: `UInt8`, `Int8`, `UInt16`, `Int16`, `UInt32`, `Int32`, `UInt64`, `Int64`, `Float32` and `Float64`
59
59
60
-
This means that every `ExtraBytes`*VLR***must** have a data type among these values (note that vectors are not directly supported). *LasDatasets.jl* supports static vectors (static sizing is essential) as user fields as well by internally separating out vector components and adding an `ExtraBytes`*VLR* for each component following the naming convention in the spec. That is, for a user field with `N` entries, the individual component names that are documented in the *VLRs* are "col [0]", "col [1]", ..., "col [N - 1]".
60
+
This means that every `ExtraBytes`*VLR***must** have a data type among these values (note that vectors are not directly supported). *LASDatasets.jl* supports static vectors (static sizing is essential) as user fields as well by internally separating out vector components and adding an `ExtraBytes`*VLR* for each component following the naming convention in the spec. That is, for a user field with `N` entries, the individual component names that are documented in the *VLRs* are "col [0]", "col [1]", ..., "col [N - 1]".
61
61
62
62
When a user passes a custom field to the system, it will firstly check that the data type for this field is either one of the above types or an `SVector` of one. If it is a vector, it will construct a list of the component element field names as above. Then, it will extract all `ExtraBytes`*VLRs* and check if any of them have matching names and update them iff they exist so their data type matches the new type supplied. If these are new fields, a new `ExtraBytes`*VLR* will be added per field name. Finally, the header is updated to reflect the new number of *VLRs*, the new data offsets and the new point record lengths.
0 commit comments