allow 'uint8' style for extra dimensions + docs

docs/index.rst

@@ -50,6 +50,7 @@ User Guide
     installation
     basic
     examples
+    lessbasic
 
 API Documentation
 =================

docs/lessbasic.rst

@@ -0,0 +1,67 @@
+=================
+Less Basic Things
+=================
+
+
+Extra Dimensions
+================
+
+The LAS Specification version 1.4 defines a standard way to add extra dimensions to
+a LAS file.
+
+In pylas you can add extra dimensions using the :meth:`pylas.lasdatas.las14.LasData.add_extra_dim` function
+
+
+The Allowed base types for an extra dimensions are:
+
++-------------------------+-------------+-------------+
+|       pylas name        | size (bits) |     type    |
++=========================+=============+=============+
+|     u1 or uint8         |     8       |  unsigned   |
++-------------------------+-------------+-------------+
+|     i1 or int8          |     8       |   signed    |
++-------------------------+-------------+-------------+
+|     u2 or uint16        |     16      |   unsigned  |
++-------------------------+-------------+-------------+
+|     i2 or int16         |     16      |    signed   |
++-------------------------+-------------+-------------+
+|     u4 or uint32        |     32      |   unsigned  |
++-------------------------+-------------+-------------+
+|     i4 or int32         |     32      |    signed   |
++-------------------------+-------------+-------------+
+|     u8 or uint64        |     64      |   unsigned  |
++-------------------------+-------------+-------------+
+|     i8 or int64         |     64      |    signed   |
++-------------------------+-------------+-------------+
+|     f4 or float         |     32      |   floating  |
++-------------------------+-------------+-------------+
+|     f8 or double        |     64      |   floating  |
++-------------------------+-------------+-------------+
+
+You can prepend the number '2' or '3' to one of the above base type to define an extra dimension
+that is array of 2 or 3 elements per points.
+Example: 3u2 -> each points will have an extra dimension that is an array of 3 * 16 bits
+
+
+Here we are adding a new dimension called "codification" where each value is stored on a 64 bit unsigned integer
+and an array field of 3 doubles for each points.
+
+
+.. code-block:: python
+
+    import pylas
+    las = pylas.read("somefile.las")
+
+    las.add_extra_dim(name="codification", type="uint64", description="More classes available")
+
+    las.add_extra_dim(name="mysterious", type="3f8")
+
+
+
+
+.. note::
+
+    As the specification of the ExtraBytesVlr appeared in the 1.4 LAS Spec, pylas restrict the ability to
+    add new dimensions to file with version >= 1.4 even if it would be totally possible to define new dimension
+    on older versions.
+    (Maybe this should change?)

pylas/extradims.py

@@ -1,23 +1,45 @@
 from . import errors
 
-extra_dims_base = ("", "u1", "i1", "u2", "i2", "u4", "i4", "u8", "i8", "f4", "f8")
+_extra_dims_base_style_1 = ("", "u1", "i1", "u2", "i2", "u4", "i4", "u8", "i8", "f4", "f8")
+_extra_dims_base_style_2 = (
+    "",
+    "uint8",
+    "int8",
+    "uint16",
+    "int16",
+    "uint32",
+    "int32",
+    "uint64",
+    "int64",
+    "float",
+    "double",
+)
 
-extra_dims_2 = tuple("2{}".format(_type) for _type in extra_dims_base[1:])
-extra_dims_3 = tuple("3{}".format(_type) for _type in extra_dims_base[1:])
-extra_dims = extra_dims_base + extra_dims_2 + extra_dims_3
+_extra_dims_style_1_array_2 = tuple("2{}".format(_type) for _type in _extra_dims_base_style_1[1:])
+_extra_dims_style_1_array_3 = tuple("3{}".format(_type) for _type in _extra_dims_base_style_1[1:])
 
-type_to_extra_dim_id = {type_str: i for i, type_str in enumerate(extra_dims)}
+_extra_dims_style_2_array_2 = tuple("2{}".format(_type) for _type in _extra_dims_base_style_2[1:])
+_extra_dims_style_2_array_3 = tuple("3{}".format(_type) for _type in _extra_dims_base_style_2[1:])
+
+_extra_dims_style_1 = _extra_dims_base_style_1 + _extra_dims_style_1_array_2 + _extra_dims_style_1_array_3
+_extra_dims_style_2 = _extra_dims_base_style_2 + _extra_dims_style_1_array_2 + _extra_dims_style_2_array_3
+
+_type_to_extra_dim_id_style_1 = {type_str: i for i, type_str in enumerate(_extra_dims_style_1)}
+_type_to_extra_dim_id_style_2 = {type_str: i for i, type_str in enumerate(_extra_dims_style_2)}
 
 
 def get_type_for_extra_dim(type_index):
     try:
-        return extra_dims[type_index]
+        return _extra_dims_style_1[type_index]
     except IndexError:
         raise errors.UnknownExtraType(type_index)
 
 
 def get_id_for_extra_dim_type(type_str):
     try:
-        return type_to_extra_dim_id[type_str]
+        return _type_to_extra_dim_id_style_1[type_str]
     except KeyError:
-        raise errors.UnknownExtraType(type_str)
+        try:
+            return _type_to_extra_dim_id_style_2[type_str]
+        except KeyError:
+            raise errors.UnknownExtraType(type_str)

pylas/lasdatas/las14.py

@@ -15,10 +15,10 @@ def update_header(self):
         if len(self.vlrs.get("WktCoordinateSystemVlr")) == 1:
             self.header.global_encoding.wkt = 1
 
-    def add_extra_dim(self, dim_name, dim_type):
-        name = dim_name.replace(" ", "_")
-        type_id = extradims.get_id_for_extra_dim_type(dim_type)
-        extra_byte = ExtraBytesStruct(data_type=type_id, name=name.encode())
+    def add_extra_dim(self, name, type, description=''):
+        name = name.replace(" ", "_")
+        type_id = extradims.get_id_for_extra_dim_type(type)
+        extra_byte = ExtraBytesStruct(data_type=type_id, name=name.encode(), description=description.encode())
 
         try:
             extra_bytes_vlr = self.vlrs.get("ExtraBytesVlr")[0]
@@ -27,7 +27,7 @@ def add_extra_dim(self, dim_name, dim_type):
             self.vlrs.append(extra_bytes_vlr)
         finally:
             extra_bytes_vlr.extra_bytes_structs.append(extra_byte)
-            self.points_data.add_extra_dims([(name, dim_type)])
+            self.points_data.add_extra_dims([(name, type)])
 
     def write_to(self, out_stream, do_compress=False):
         if do_compress and self.points_data.point_format_id >= 6:

pylas/vlrs/known.py

@@ -200,6 +200,11 @@ def type_tuple(self):
     def size():
         return ctypes.sizeof(ExtraBytesStruct)
 
+    def __repr__(self):
+        return "<ExtraBytesStruct({}, {}, {})>".format(
+            *self.type_tuple(), self.description
+        )
+
 
 class ExtraBytesVlr(BaseVLR, KnownVLR):
     def __init__(self):