Merge pull request #49 from fugro-oss/ModifyRecords

Flexibly Modify Point Contents

Project.toml

@@ -1,7 +1,7 @@
 name = "LASDatasets"
 uuid = "cc498e2a-d443-4943-8f26-2a8a0f3c7cdb"
 authors = ["BenCurran98 <b.curran@fugro.com>"]
-version = "0.3.3"
+version = "0.4.0"
 
 [deps]
 BufferedStreams = "e1450e63-4bb3-523b-b2a4-4ffa8c0fd77d"

docs/src/header.md

@@ -38,6 +38,7 @@ You can also modify certain fields in the header, but one should note that for s
 
 ```@docs; canonical = false
 set_las_version!
+set_point_format!
 set_spatial_info!
 set_point_data_offset!
 set_point_record_length!

docs/src/interface.md

@@ -70,18 +70,47 @@ Alternatively, if you just have the point cloud data as a Table:
 using StaticArrays
 using TypedTables
 
-pc = Table(position = rand(SVector{3, Float64}, 10), classification = rand(UIn8, 10))
+pc = Table(position = rand(SVector{3, Float64}, 10), classification = rand(UInt8, 10))
 save_las("my_las.las", pc)
 ```
 
 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. 
 
 ## Modifying LAS Contents
-You can modify point fields in your `LASDataset` by adding new columns or merging in values from an existing vector.
+You can modify point fields in your `LASDataset` by adding new columns or merging in values from an existing vector. Additionally, you can add and remove points from a dataset. When adding points, the user is responsible for correctly setting the appropriate fields (e.g. synthetic flags).
 
 ```@docs; canonical = false
 add_column!
 merge_column!
+add_points!
+remove_points!
+```
+
+For example, if you want to add a set of synthetic points to your dataset, you can run:
+```julia
+las = load_las("my_las.las")
+# note - we need to set a synthetic column here for the existing points before we append points with this field
+add_column!(las, :synthetic, falses(number_of_points(las)))
+synthetic_points = Table(position = rand(SVector{3, Float64}, 5), classification = rand(UInt8, 5), synthetic = trues(5))
+add_points!(las, synthetic_points)
+```
+
+You can remove points from your data using the `remove_points!` function and specifying the indices of the points you wish to delete (these will be indexing into the list of points in order). E.g.
+```julia
+remove_points!(las, 11:15)
+```
+
+Note that you can also modify the contents of your points by acting directly on the tabular pointcloud data. **Note:** this should **not** be used to add/remove points or point fields, since this will cause a conflict between the data in your points and the file header. Intended use is for operations that preserve the number of points and the existing fields. 
+For example:
+
+```julia
+pc = get_pointcloud(las)
+
+# shuffle the order of the points based on point positions
+pc = pc[sortperm(pc.position)]
+
+# set all classifications to 0
+pc.classification .= 0
 ```
 
 You can also add or remove *(E)VLRs* using the following functions, and set an existing *(E)VLR* as *superseded* if it's an old copy of a record.

docs/src/vlrs.md

@@ -62,7 +62,7 @@ You can then read the *LAS* data and extract the classification lookup:
 las = load_las("pc.las")
 # look for the classification lookup VLR by checking for its user and record IDs
 lookup_vlr = extract_vlr_type(get_vlrs(las), "LASF_Spec", 0)
-lookup = get_data(lookup_vlr[1])
+lookup = get_data(lookup_vlr)
 ```
 
 ### Text Area Descriptions
@@ -150,7 +150,7 @@ So in our example, we can tell the system that records containing data of type `
 @register_vlr_type MyType "My Custom Records" collect(1:100)
 ```
 
-And now we can save our `MyType` *VLRs* into a *LAS* file in the same way as we did above for the register *VLR* types. Note that you can use the function `extract_vlr_type` on your collection of *VLRs* to pull out any *VLRs* with a specific user ID and record ID.
+And now we can save our `MyType` *VLRs* into a *LAS* file in the same way as we did above for the register *VLR* types. Note that you can use the function `extract_vlr_type` on your collection of *VLRs* to pull out the *VLR* with a specific user ID and record ID. 
 
 ```@docs; canonical = false
 extract_vlr_type

src/LASDatasets.jl

@@ -39,7 +39,7 @@ export scan_direction, user_data
 # header interface
 export LasHeader, is_standard_gps, is_wkt, file_source_id, global_encoding, las_version, system_id, software_id, creation_day_of_year, creation_year
 export header_size, point_data_offset, point_record_length, record_format, point_format,  number_of_points, number_of_vlrs, number_of_evlrs, evlr_start, spatial_info, scale, num_return_channels
-export set_las_version!, set_spatial_info!, set_point_data_offset!, set_point_format!, set_point_record_length!, set_point_record_count!, set_num_vlr!, set_num_evlr!, set_gps_week_time_bit!
+export set_las_version!, set_point_format!, set_spatial_info!, set_point_data_offset!, set_point_format!, set_point_record_length!, set_point_record_count!, set_num_vlr!, set_num_evlr!, set_gps_week_time_bit!
 export set_gps_standard_time_bit!, is_internal_waveform, is_external_waveform, unset_wkt_bit!
 export set_waveform_external_bit!, set_waveform_internal_bit!, set_synthetic_return_numbers_bit!, unset_synthetic_return_numbers_bit!
 export set_wkt_bit!, get_number_of_points_by_return, set_number_of_points_by_return!, waveform_record_start
@@ -55,7 +55,7 @@ export get_classes, get_description, set_description!
 export @register_vlr_type, read_vlr_data, extract_vlr_type
 
 export LASDataset, get_header, get_pointcloud, get_vlrs, get_evlrs, get_user_defined_bytes, get_unit_conversion
-export add_column!, merge_column!, add_vlr!, remove_vlr!, set_superseded!
+export add_column!, add_points!, remove_points!, merge_column!, add_vlr!, remove_vlr!, set_superseded!
 
 # I/O methods
 export load_las, load_pointcloud, save_las, load_header, load_vlrs