Added autogenerated sphinx documentation

docs/quickstart.rst

@@ -0,0 +1,190 @@
+Quickstart Guide
+================
+
+This guide will get you up and running with ``read_aconity_layers`` in just a few minutes.
+
+Basic Usage
+-----------
+
+Reading All Layers from a Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The most common use case is reading all layer files from a directory:
+
+.. code-block:: python
+
+   import read_aconity_layers as ral
+   import numpy as np
+
+   # Read all .pcd files from a directory
+   data = ral.read_layers("/path/to/your/layer/files/")
+
+   print(f"Loaded {data.shape[0]} data points")
+   print(f"Data shape: {data.shape}")
+   print(f"Columns: [x, y, z, data1, data2]")
+
+Reading Specific Files
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to read only specific layer files:
+
+.. code-block:: python
+
+   import read_aconity_layers as ral
+
+   # List of specific files to read
+   files = [
+       "/path/to/0.1.pcd",
+       "/path/to/0.2.pcd",
+       "/path/to/0.3.pcd"
+   ]
+
+   data = ral.read_selected_layers(files)
+
+Reading a Single Layer
+~~~~~~~~~~~~~~~~~~~~~~
+
+For processing individual layers:
+
+.. code-block:: python
+
+   import read_aconity_layers as ral
+
+   # Read just one layer file
+   layer_data = ral.read_layer("/path/to/single_layer.pcd")
+
+   # Extract coordinates
+   x_coords = layer_data[:, 0]
+   y_coords = layer_data[:, 1]
+   z_coords = layer_data[:, 2]
+
+Working with the Data
+---------------------
+
+Understanding the Data Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All functions return NumPy arrays with 5 columns:
+
+* **Column 0**: X coordinates (corrected)
+* **Column 1**: Y coordinates (corrected)
+* **Column 2**: Z coordinates (layer height)
+* **Column 3**: Original data column 3
+* **Column 4**: Original data column 4
+
+The X and Y coordinates are automatically corrected using the calibration
+formulas built into the library.
+
+Example: Basic Data Analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import read_aconity_layers as ral
+   import numpy as np
+   import matplotlib.pyplot as plt
+
+   # Load data
+   data = ral.read_layers("/path/to/layers/")
+
+   # Basic statistics
+   print(f"X range: {data[:, 0].min():.2f} to {data[:, 0].max():.2f}")
+   print(f"Y range: {data[:, 1].min():.2f} to {data[:, 1].max():.2f}")
+   print(f"Z range: {data[:, 2].min():.2f} to {data[:, 2].max():.2f}")
+
+   # Plot layer distribution
+   unique_z = np.unique(data[:, 2])
+   layer_counts = [np.sum(data[:, 2] == z) for z in unique_z]
+
+   plt.figure(figsize=(10, 6))
+   plt.plot(unique_z, layer_counts)
+   plt.xlabel('Layer Height (Z)')
+   plt.ylabel('Number of Points')
+   plt.title('Points per Layer')
+   plt.show()
+
+Example: Processing by Layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import read_aconity_layers as ral
+   import numpy as np
+
+   # Read data
+   data = ral.read_layers("/path/to/layers/")
+
+   # Group by Z coordinate (layer)
+   unique_z = np.unique(data[:, 2])
+
+   layer_stats = []
+   for z in unique_z:
+       layer_mask = data[:, 2] == z
+       layer_points = data[layer_mask]
+
+       stats = {
+           'z': z,
+           'point_count': len(layer_points),
+           'x_mean': layer_points[:, 0].mean(),
+           'y_mean': layer_points[:, 1].mean(),
+           'data1_mean': layer_points[:, 3].mean(),
+           'data2_mean': layer_points[:, 4].mean(),
+       }
+       layer_stats.append(stats)
+
+   # Convert to structured array for easier analysis
+   layer_stats = np.array(layer_stats)
+
+Performance Tips
+----------------
+
+Parallel Processing
+~~~~~~~~~~~~~~~~~~~
+
+The library automatically uses parallel processing for multiple files.
+For best performance:
+
+* Use ``read_layers()`` for directories with many files
+* The library will automatically use all available CPU cores
+* Larger numbers of files will see better speedup
+
+Memory Usage
+~~~~~~~~~~~~
+
+For very large datasets:
+
+* Consider processing files in batches if memory is limited
+* Use ``read_selected_layers()`` to process subsets
+* The library streams data efficiently, but the final arrays are held in memory
+
+File Organization
+~~~~~~~~~~~~~~~~~
+
+For optimal performance:
+
+* Keep layer files in a single directory when using ``read_layers()``
+* Use consistent naming (the Z coordinate is extracted from the filename)
+* Ensure files are properly formatted space-delimited text
+
+Error Handling
+--------------
+
+The library provides detailed error messages for common issues:
+
+.. code-block:: python
+
+   import read_aconity_layers as ral
+
+   try:
+       data = ral.read_layers("/path/to/layers/")
+   except IOError as e:
+       print(f"File read error: {e}")
+   except RuntimeError as e:
+       print(f"Processing error: {e}")
+
+Next Steps
+----------
+
+* Check out the full :doc:`python/index` for detailed function documentation
+* See :doc:`development` if you want to contribute to the project
+* For performance-critical applications, review the :doc:`rust/index`