Docs and CI/CD #5

BenCurran98 · 2024-04-22T00:03:04Z

You can view a preview of the documentation here

Signed-off-by: BenCurran98 <b.curran@fugro.com>

mazadbakht · 2024-04-23T07:01:12Z

docs/src/interface.md

+las = load_las("example.las")
+
+# only extract position and classification
+las = load_las("example", [:position, :classification])


should not this be example.las/z?

docs/src/interface.md

i-kieu · 2024-04-23T07:08:23Z

docs/src/interface.md

+```
+
+## Reading
+To read the entire contents of a *LAS* or *LAZ* file, you can use the `load_las` function. This return a `LasDataset` with all the quantities listed above. You also have the option of only loading certain point fields.


Second sentence:
"This returns a [...]"
Also "the quantities" are returned? Do you mean to say qualities?

docs/src/interface.md

i-kieu · 2024-04-23T07:14:29Z

docs/src/interface.md

+```
+
+## Writing
+You can write the contents of your `LasDataset` to a file by using the `save_las` function. Note that this takes either a `LasDataset` as a whole, or a tabular point cloud, *(E)VLRs* and user-defined bytes separately.


The note reads funny.
"Note that this takes either a LasDataset as a whole, or as a tabular point cloud, with (E)VLRs and user-defined bytes [something missing here] separately."

docs/src/interface.md

i-kieu · 2024-04-23T07:19:54Z

docs/src/internals.md

+
+## Data Consistency
+
+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 usinjg 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.


I wish you would do the one-sentence-per-line-of-code thing 😆

Typo in second sentence fifth word, "using".

i-kieu · 2024-04-23T07:21:51Z

docs/src/internals.md

+LAS.FullRecord
+```
+
+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.


i-kieu · 2024-04-23T07:27:46Z

docs/src/internals.md

+* How many bytes the point format is
+* How many user fields in this record and their data size in bytes
+* How many undocumented bytes there are


Grammatically since this is a sentence leading into a list of dot-points:
"""

How many bytes the point format is,

How many user fields there are in the record and their data size in bytes, and

How many undocumented bytes there are.

"""

i-kieu · 2024-04-23T07:30:05Z

docs/src/internals.md

+
+Firstly, the *LAS* 1.4 spec officially supports the following data types directly: `UInt8`, `Int8`, `UInt16`, `Int16`, `UInt32`, `Int32`, `UInt64`, `Int64`, `Float32` and `Float64`
+
+This means that every `ExtraBytes` *VLR* **must** be have a data type among these values (note that vectors are not directly supported). *LAS.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]".


First sentence eighth word "be" does not need to be there.

i-kieu · 2024-04-23T07:33:09Z

docs/src/internals.md

+
+This means that every `ExtraBytes` *VLR* **must** be have a data type among these values (note that vectors are not directly supported). *LAS.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]".
+
+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 naems 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 offstes and the new point record lengths.


Second sentence third last word typo, "names".
Third sentence I would recommend typing out iff to if and only if.
Last sentence seventh last word typo, "offsets".

i-kieu · 2024-04-23T07:41:47Z

docs/src/user_fields.md

+las = load_las("my_pc.las", [:position, :classification, :thing])
+```
+
+It's also worth mentioning too that you can save "undocumented bytes" to any point as well by labelling them with the column `:undocumented_bytes`. In practice, it is possible to either have point records with user fields and undocumented bytes, just one or the other, or neither (just the *LAS* point itself).


Don't need the "too" after "It's also worth mentioning", and you can probably remove the "as well" after the "to any point".
Second sentence might read more clearly without the "either".

i-kieu · 2024-04-23T07:46:20Z

docs/src/vlrs.md

+OGC_WKT
+```
+
+One benefit of using the *OGC WKT* is that you can specify what units of measurement are used for your point coordinates along both the *XY* plane and the *Z* axis. When reading a *LAS* file, the system can detect if an *OGC WKT* is present and will, if requested by the user, convert the point coordinates to metres.


Maybe I am being picky with this one but
"point coordinates both in the XY plane and along the Z axis."

i-kieu · 2024-04-23T07:48:35Z

docs/src/vlrs.md

+TextAreaDescription
+```
+
+Using the dataset `las` above, we can add a description as follows (and save/read it as we did above). Note you can also rrepeat the way the Classification Lookup was saved above too.


Typo second sentence, "repeat".

i-kieu · 2024-04-23T07:49:48Z

docs/src/vlrs.md

+
+### Extra Bytes
+
+Extra Bytes *VLRs* are a type of *VLR* that documents any user fields that have been added to point records in your *LAS* data. You can find an in-depth explaination of how to save/load user defined fields to your points [here](./user_fields.md). 


Typo second sentence, "explanation".

i-kieu · 2024-04-23T07:54:03Z

src/header.jl

+"""
+    $(TYPEDSIGNATURES)
+
+Set the spatial information associate to points in a LAS file with a header `header`


"associated"

Signed-off-by: BenCurran98 <b.curran@fugro.com>

MeganDawson42 · 2024-04-25T23:12:34Z

src/header.jl

+    $(TYPEDSIGNATURES)
+
+Get the LAS specification version from a header `h`
+"""
 las_version(h::LasHeader) = h.las_version


It doesn't work in this case as we are doing a few other manipulations on some of the other fields... but if we're going to make functions on accessing all the fields, might be worth making something like this in utils / somewhere... or making this into a macro...

oh wait.. if you change the fieldname it would change... lol

Yeah it's tricky do do in a non-manual, nice way

BenCurran98 changed the title ~~Add initial github actions~~ Docs and CI/CD Apr 22, 2024

BenCurran98 force-pushed the DocsAndCICD branch 2 times, most recently from 2f4c89b to 1db23ba Compare April 22, 2024 23:15

BenCurran98 added 7 commits April 23, 2024 12:55

Add initial github actions

80cb99f

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Remove coverage for now

4dfe15b

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Draft docs files

b4f9110

Signed-off-by: BenCurran98 <b.curran@fugro.com>

User defined fields

b5554fc

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Update docs pages

08ea5f2

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Header docs

f5b7c5a

Signed-off-by: BenCurran98 <b.curran@fugro.com>

VLR docs

005ab24

Signed-off-by: BenCurran98 <b.curran@fugro.com>

BenCurran98 force-pushed the DocsAndCICD branch from 1db23ba to 005ab24 Compare April 23, 2024 02:56

BenCurran98 added 5 commits April 23, 2024 14:17

VLR docs

2c5e551

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Restrict to >=1.8 compat

b8e098c

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Try fixing docs permissions

a0ee5c2

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Remove deprecated gh actions versions

6f4b01c

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Add docs for internals

810bba0

Signed-off-by: BenCurran98 <b.curran@fugro.com>

BenCurran98 marked this pull request as ready for review April 23, 2024 06:46

BenCurran98 requested review from n6171028, MeganDawson42, mazadbakht, zqiaofugro and i-kieu April 23, 2024 06:47

mazadbakht reviewed Apr 23, 2024

View reviewed changes

i-kieu reviewed Apr 23, 2024

View reviewed changes

docs/src/interface.md Show resolved Hide resolved

i-kieu reviewed Apr 23, 2024

View reviewed changes

docs/src/interface.md Show resolved Hide resolved

i-kieu reviewed Apr 23, 2024

View reviewed changes

docs/src/interface.md Show resolved Hide resolved

i-kieu reviewed Apr 23, 2024

View reviewed changes

i-kieu approved these changes Apr 23, 2024

View reviewed changes

BenCurran98 added 2 commits April 24, 2024 07:25

PR feedback

2f03cc3

Signed-off-by: BenCurran98 <b.curran@fugro.com>

Fix bug in unit conversion

bb13b33

Signed-off-by: BenCurran98 <b.curran@fugro.com>

MeganDawson42 reviewed Apr 25, 2024

View reviewed changes

MeganDawson42 approved these changes Apr 25, 2024

View reviewed changes

n6171028 approved these changes Apr 26, 2024

View reviewed changes

BenCurran98 merged commit 190a6b4 into main Apr 29, 2024
9 checks passed

BenCurran98 deleted the DocsAndCICD branch April 29, 2024 00:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs and CI/CD #5

Docs and CI/CD #5

BenCurran98 commented Apr 22, 2024 •

edited

Loading

mazadbakht Apr 23, 2024

i-kieu Apr 23, 2024 •

edited

Loading

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024 •

edited

Loading

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

i-kieu Apr 23, 2024

MeganDawson42 Apr 25, 2024

MeganDawson42 Apr 25, 2024

BenCurran98 Apr 29, 2024


		## Data Consistency

		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 usinjg 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.


		Firstly, the LAS 1.4 spec officially supports the following data types directly: `UInt8`, `Int8`, `UInt16`, `Int16`, `UInt32`, `Int32`, `UInt64`, `Int64`, `Float32` and `Float64`

		This means that every `ExtraBytes` VLR must be have a data type among these values (note that vectors are not directly supported). LAS.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]".


		This means that every `ExtraBytes` VLR must be have a data type among these values (note that vectors are not directly supported). LAS.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]".

		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 naems 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 offstes and the new point record lengths.


		### Extra Bytes

		Extra Bytes VLRs are a type of VLR that documents any user fields that have been added to point records in your LAS data. You can find an in-depth explaination of how to save/load user defined fields to your points [here](./user_fields.md).

Docs and CI/CD #5

Docs and CI/CD #5

Conversation

BenCurran98 commented Apr 22, 2024 • edited Loading

Choose a reason for hiding this comment

i-kieu Apr 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

i-kieu Apr 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BenCurran98 commented Apr 22, 2024 •

edited

Loading

i-kieu Apr 23, 2024 •

edited

Loading

i-kieu Apr 23, 2024 •

edited

Loading