Adding some doctrings

pylas/headers/rawheader.py

@@ -156,12 +156,11 @@ def date(self):
 
     @date.setter
     def date(self, date):
+        """ Returns the date of file creation as a python date object
+        """
         self.creation_year = date.year
         self.creation_day_of_year = date.timetuple().tm_yday
 
-    def write_to(self, out_stream):
-        out_stream.write(bytes(self))
-
     @property
     def point_format_id(self):
         return compression.compressed_id_to_uncompressed(self._point_data_format_id)
@@ -222,6 +221,8 @@ def maxs(self, value):
 
     @property
     def scales(self):
+        """ Returns the scaling values of x, y, z as a numpy array
+        """
         return np.array([self.x_scale, self.y_scale, self.z_scale])
 
     @scales.setter
@@ -230,12 +231,17 @@ def scales(self, value):
 
     @property
     def offsets(self):
+        """ Returns the offsets values of x, y, z as a numpy array
+        """
         return np.array([self.x_offset, self.y_offset, self.z_offset])
 
     @offsets.setter
     def offsets(self, value):
         self.x_offsets, self.y_offsets, self.z_offsets = value
 
+    def write_to(self, out_stream):
+        out_stream.write(bytes(self))
+
     def __repr__(self):
         return "<LasHeader({})>".format(self.version)
 

pylas/lib.py

@@ -67,7 +67,7 @@ def open_las(source, closefd=True):
 def read_las(source, closefd=True):
     """ Entry point for reading las data in pylas
 
-    Reads the whole file in memory.
+    Reads the whole file into memory.
 
     >>> las = read_las("pylastests/simple.las")
     >>> las.classification
@@ -93,6 +93,9 @@ def read_las(source, closefd=True):
 
 
 def mmap_las(filename):
+    """ MMap a file, much like laspy did, very experimental
+    not well tested
+    """
     return LasMMAP(filename)
 
 
@@ -312,6 +315,11 @@ def merge_las(*las_files):
 
 
 def write_then_read_again(las, do_compress=False):
+    """ writes the given las into memory using BytesIO and 
+    reads it again, returning the newly read file.
+
+    Mostly used for testing purposes, without having to write to disk
+    """
     out = io.BytesIO()
     las.write(out, do_compress=do_compress)
     out.seek(0)

pylas/point/packing.py

@@ -100,20 +100,40 @@ def repack_sub_fields(structured_array, point_format_id):
 
     for dim_name in repacked_array.dtype.names:
         if dim_name in composed_dims:
-            for sub_field in composed_dims[dim_name]:
-                try:
-                    pack(
-                        repacked_array[dim_name],
-                        structured_array[sub_field.name],
-                        sub_field.mask,
-                        inplace=True,
-                    )
-                except OverflowError as e:
-                    raise OverflowError(
-                        "Error repacking {} into {}: {}".format(
-                            sub_field.name, dim_name, e
-                        )
-                    )
+            _repack_composed_dim(dim_name, composed_dims[dim_name], repacked_array, structured_array)
         else:
             repacked_array[dim_name] = structured_array[dim_name]
     return repacked_array
+
+
+def _repack_composed_dim(dim_name, sub_fields, repacked_array, structured_array):
+    """ Repack the fields of a composed dimension together
+
+    Parameters
+    ----------
+    sub_fields: list of SubField, the sub fields of the dimension
+    dim_name: name of the composed dimension
+    repacked_array: structured array in which the composed_dim will be repacked
+    structured_array: structured array from which sub fields are taken
+
+    Raises
+    ------
+
+    OverflowError if the values in any of the sub fields are greater than
+    allowed
+
+    """
+    for sub_field in sub_fields:
+        try:
+            pack(
+                repacked_array[dim_name],
+                structured_array[sub_field.name],
+                sub_field.mask,
+                inplace=True,
+            )
+        except OverflowError as e:
+            raise OverflowError(
+                "Error repacking {} into {}: {}".format(
+                    sub_field.name, dim_name, e
+                )
+            )

pylas/vlrs/known.py

@@ -1,4 +1,4 @@
-""" The definition of the VLR Header, VLR, and VRL List as well as all the KnownVLR
+""" The definition of the VLR Header, VLR, the KnownVLRs
  are in this module.
 
  A KnownVLR is a VLR that we know how to parse its record_data
@@ -152,6 +152,9 @@ def official_record_ids():
 
 
 class LasZipVlr(BaseKnownVLR):
+    """ Contains the informations needed by laszip & lazperf
+    to compress the point records.
+    """
     def __init__(self, data):
         super().__init__(description="http://laszip.org")
         self.record_data = data
@@ -490,6 +493,10 @@ def official_record_ids():
 
 
 def vlr_factory(raw_vlr):
+    """ Given a raw_vlr tries to find its corresponding KnownVLR class
+    that can parse its data.
+    If no KnownVLR implementation is found, returns a VLR (record_data will still be bytes)
+    """
     user_id = raw_vlr.header.user_id.rstrip(NULL_BYTE).decode()
     known_vlrs = BaseKnownVLR.__subclasses__()
     for known_vlr in known_vlrs: