### Install PyntCloud Library

Source: https://github.com/daavoo/pyntcloud/blob/main/README.md

This snippet provides the command-line instruction to install the PyntCloud library using pip, the Python package installer.

```bash
pip install pyntcloud
```

--------------------------------

### PyntCloud Core Class Workflow Example

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/introduction.rst

This Python snippet demonstrates the recommended workflow for using the `PyntCloud` core class. It illustrates how to load a point cloud from a file, add spatial structures like a k-d tree, find k-nearest neighbors, compute scalar fields (e.g., eigen values), and apply filters (e.g., bounding box). This example showcases the integration of various pyntcloud modules through a single `PyntCloud` instance.

```python
from pyntcloud import PyntCloud
# io
cloud = PyntCloud.from_file("some_file.ply")
# structures
kdtree_id = cloud.add_structure("kdtree")
# neighbors
k_neighbors = cloud.get_neighbors(k=5, kdtree=kdtree_id)
# scalar_fields
ev = cloud.add_scalar_field("eigen_values", k_neighbors=k_neighbors)
# filters
f = cloud.get_filter("BBOX", min_x=0.1, max_x=0.8)
# ...
```

--------------------------------

### Install pyntcloud using pip

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/installation.rst

Installs the pyntcloud library from PyPI using the pip package manager. Requires Python 3.5 or greater.

```bash
pip install pyntcloud
```

--------------------------------

### Clone Repository and Install in Editable Mode

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/contributing.rst

Instructions to clone the pyntcloud repository from GitHub and install it in editable mode, allowing for direct development and testing of changes.

```bash
git clone https://github.com/daavoo/pyntcloud.git
pip install -e pyntcloud
```

--------------------------------

### Install pyntcloud using conda

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/installation.rst

Installs the pyntcloud library using the conda package manager from the conda-forge channel. This method is an alternative to pip installation.

```bash
conda install pyntcloud -c conda-forge
```

--------------------------------

### Integrate PyntCloud with PyVista for Data Conversion

Source: https://github.com/daavoo/pyntcloud/blob/main/README.md

This example demonstrates the seamless integration of PyntCloud with PyVista for 3D data conversion. It shows how to create a PyntCloud instance from a PyVista object using `from_instance` and convert a PyntCloud object back to a PyVista mesh using `to_instance`.

```python
import pyvista as pv
from pyntcloud import PyntCloud

# FROM PyVista
original_point_cloud = pv.read("diamond.ply")
cloud = PyntCloud.from_instance("pyvista", original_point_cloud)

# TO PyVista
cloud = PyntCloud.from_file("diamond.ply")
converted_triangle_mesh = cloud.to_instance("pyvista", mesh=True)
```

--------------------------------

### Write PyntCloud Instance to File using PyntCloud.to_file

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/io.rst

Illustrates how to save a PyntCloud instance to a file. The example shows how to specify the output file format (e.g., .obj) and optionally select which internal components (like 'points' or 'mesh') of the point cloud should be saved.

```python
# my_point_cloud is a PyntCloud instance
my_point_cloud.to_file("out_file.obj", internal=["points", "mesh"])
```

--------------------------------

### Process 3D Point Cloud Data with PyntCloud

Source: https://github.com/daavoo/pyntcloud/blob/main/README.md

This example demonstrates a concise workflow for processing 3D point clouds using PyntCloud. It includes loading a PLY file, adding scalar fields (HSV), building a voxel grid structure, sampling the nearest points, and saving the processed data to an NPZ file.

```python
from pyntcloud import PyntCloud

cloud = PyntCloud.from_file("some_file.ply")

cloud.add_scalar_field("hsv")

voxelgrid_id = cloud.add_structure("voxelgrid", n_x=32, n_y=32, n_z=32)

new_cloud = cloud.get_sample("voxelgrid_nearest", voxelgrid_id=voxelgrid_id, as_PyntCloud=True)

new_cloud.to_file("out_file.npz")
```

--------------------------------

### Add VoxelGrid Structure

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers.rst

Example of adding a VoxelGrid structure to a point cloud. This step is required before using any VoxelGrid-based samplers.

```python
voxelgrid = pointcloud.add_structure("voxelgrid", ...)
```

--------------------------------

### RadiusOutlierRemoval Filter Example

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/filters_dev.rst

An example of a concrete filter class, `RadiusOutlierRemoval`, demonstrating how to implement a specific filter. It inherits from a submodule base class (e.g., `Filter_KDTree` if it uses a KDTree) and overrides `__init__` to accept user-defined parameters (`r` for radius and `k` for neighbors) and `compute` to perform the actual filtering logic.

```APIDOC
class RadiusOutlierRemoval(Filter_SubmoduleBase): # Placeholder for actual base class
  __init__(self, pyntcloud_instance: PyntCloud, r: float, k: int)
    pyntcloud_instance: The PyntCloud instance.
    r: The radius parameter for outlier removal.
    k: The number of neighbors parameter.
  compute(self) -> numpy.ndarray[bool]
    Purpose: Generates the boolean array for radius-based outlier removal using 'r' and 'k'.
```

--------------------------------

### PyntCloud Class API Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/PyntCloud.rst

Comprehensive API documentation for the PyntCloud class, detailing its core purpose, predefined attributes, and categorized methods for manipulating point cloud data. Methods are grouped by their functionality: 'add' for incorporating new information, 'get' for extracting information, 'I/O' for file operations, and 'other' for general utilities.

```APIDOC
Class: PyntCloud
  Description: Core class for manipulating point clouds, providing attributes and methods for data storage and operations.
  Attributes:
    - centroid: Predefined attribute.
    - mesh: Predefined attribute.
    - points: Predefined attribute.
    - structures: Predefined attribute.
    - xyz: Predefined attribute.
    - (User-defined attributes can also be added)
  Methods:
    ADD METHODS:
      - add_scalar_field(): Incorporates new scalar field information.
      - add_structure(): Incorporates new structural information.
    GET METHODS:
      - get_filter(): Returns filtered information.
      - get_sample(): Returns sampled information.
      - get_neighbors(): Returns neighbor information.
      - get_mesh_vertices(): Returns mesh vertices.
    I/O METHODS:
      - from_file(): (Static method) Reads point cloud data from a file.
      - to_file(): Writes point cloud data to a file.
    OTHER METHODS:
      - apply_filter(): Applies a filter to the point cloud.
      - split_on(): Splits the point cloud based on criteria.
      - plot(): Plots the point cloud.
```

--------------------------------

### Run Flake8 for Code Style and Syntax Checks

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/contributing.rst

Executes the flake8 tool to identify and report syntax errors, style guide violations, and other code quality issues within the pyntcloud project.

```bash
flake8
```

--------------------------------

### Generating Scatter Matrix for PyntCloud Points

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/points.rst

This example shows how to create a scatter matrix plot for the point cloud data. It uses `pandas.tools.plotting.scatter_matrix` to visualize relationships between 'x', 'y', and 'z' coordinates, with kernel density estimation on the diagonal.

```python
from pandas.tools.plotting import scatter_matrix

scatter_matrix(cloud.points, diagonal="kde", figsize=(8,8))
```

--------------------------------

### SphericalCoordinates Scalar Field Class Example

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/scalar_fields_dev.rst

An example of a concrete scalar field class, SphericalCoordinates, demonstrating how to inherit from a submodule base class (e.g., ScalarField_XYZ) and override the compute method. It also illustrates how to accept user-defined parameters via the __init__ method.

```APIDOC
pyntcloud.scalar_fields.sf_xyz.SphericalCoordinates

Example of overriding `__init__` to accept user parameters (e.g., 'degrees' for output format).
```

--------------------------------

### Define and plot polylines with multiple arbitrary vertices

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] Polylines.ipynb

This example demonstrates defining polylines with more than two vertices, enabling complex shapes. Two 'pink' polylines are created with multiple connected segments and then visualized using `cloud.plot()`.

```python
polylines = [
    {"color": "pink", "vertices": [[0, 0, 0], [7, 0, 0], [10, 0, 10], [12, -2, 10]]},
    {"color": "pink", "vertices": [[0, 0, 0], [0, 7, 0], [0, 10, 10]]}
]
```

```python
cloud.plot(polylines=polylines)
```

--------------------------------

### Getting Statistical Summary of PyntCloud Points

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/points.rst

This code loads a point cloud and then uses the `describe()` method of the underlying pandas DataFrame to generate descriptive statistics for the 'x', 'y', and 'z' coordinates. This provides quick insights into the distribution of point data.

```python
from pyntcloud import PyntCloud

cloud = PyntCloud.from_file("test/data/filters/filters.ply")

cloud.points.describe()
```

--------------------------------

### RandomMesh Specific Sampler Class API Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers_dev.rst

An example of a specific sampler class that inherits from a submodule base class (e.g., `Sampler_Mesh`). It overrides the `Sampler.compute` method to perform the actual sampling and may override `__init__` to accept user-defined parameters, such as whether to use RGB or normal information.

```APIDOC
RandomMesh:
  Inherits from: (Submodule Base Class, e.g., Sampler_Mesh)
  __init__(pyntcloud_instance: PyntCloud, use_rgb: bool = False, use_normals: bool = False, ...):
    pyntcloud_instance: The PyntCloud object.
    use_rgb: Boolean indicating if RGB information should be used.
    use_normals: Boolean indicating if normal information should be used.
  Methods:
    compute():
      Description: Generates the random mesh sample based on configured parameters.
```

--------------------------------

### Instantiating PyntCloud with NumPy Array (Incorrect)

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/points.rst

This example attempts to instantiate a `PyntCloud` object directly with a NumPy array. It illustrates a restriction: the `points` argument must be a pandas DataFrame, not a NumPy array, resulting in a `TypeError`.

```python
import numpy as np

from pyntcloud import PyntCloud

points = np.random.rand(1000, 3)

cloud = PyntCloud(points)
```

--------------------------------

### PyntCloud Scalar Fields Requiring K Neighbors

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/scalar_fields.rst

API documentation and usage example for scalar field classes that require information about the k-nearest neighbors of each point. This is often used for local neighborhood analysis.

```Python
k_neighbros = pointcloud.get_k_neighbors(k=10, ...)
```

```APIDOC
Normals:
  Description: Computes the normal vectors for each point.
EigenValues:
  Description: Computes the eigen values based on k-neighbors.
EigenDecomposition:
  Description: Performs eigen decomposition based on k-neighbors.
```

--------------------------------

### PyntCloud Scalar Fields Requiring VoxelGrid

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/scalar_fields.rst

API documentation and usage example for scalar field classes that depend on a pre-computed VoxelGrid structure. These fields are often related to spatial partitioning.

```Python
voxelgrid = self.add_structure("voxelgrid", ...)
```

```APIDOC
EuclideanClusters:
  Description: Computes Euclidean clusters based on the VoxelGrid.
VoxelN:
  Description: Computes the number of points in each voxel.
VoxelX:
  Description: Computes the X coordinate of the voxel center.
VoxelY:
  Description: Computes the Y coordinate of the voxel center.
VoxelZ:
  Description: Computes the Z coordinate of the voxel center.
```

--------------------------------

### PyntCloud Scalar Fields Requiring Eigen Values

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/scalar_fields.rst

API documentation and usage example for scalar field classes that depend on pre-computed eigen values. These fields provide insights into local geometric properties.

```Python
ev = pointcloud.add_scalar_field("eigen_values", ...)
```

```APIDOC
Anisotropy:
  Description: Computes the anisotropy scalar field.
Curvature:
  Description: Computes the curvature scalar field.
Eigenentropy:
  Description: Computes the eigenentropy scalar field.
EigenSum:
  Description: Computes the sum of eigen values scalar field.
Linearity:
  Description: Computes the linearity scalar field.
Omnivariance:
  Description: Computes the omnivariance scalar field.
Planarity:
  Description: Computes the planarity scalar field.
```

--------------------------------

### PyntCloud.get_sample Function Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers.rst

Provides access to all available samplers within PyntCloud.

```APIDOC
PyntCloud.get_sample
```

--------------------------------

### Integrating New Samplers into PyntCloud

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers_dev.rst

This section outlines the necessary steps to integrate a newly created sampler into the PyntCloud library, covering testing, importing, registering with an alias in `ALL_SAMPLERS`, and updating documentation.

```Python
# 1. Add tests for the new sampler(s)
# File: test/test_samplers.py
# Example:
# def test_new_sampler_functionality():
#     # ... test code ...
#     assert result == expected

# 2. Import your new sampler(s) and/or submodule(s)
# File: pyntcloud/samplers/__init__.py
from .s_your_new_submodule import YourNewSubmoduleSampler
from .s_your_specific_sampler import YourSpecificSampler

# 3. Include them in the ALL_SAMPLERS dictionary, giving them a string alias
# File: pyntcloud/samplers/__init__.py
ALL_SAMPLERS = {
    # ... existing samplers ...
    "your_new_sampler_alias": YourSpecificSampler,
    "your_new_submodule_alias": YourNewSubmoduleSampler
}

# 4. Document them in the PyntCloud.get_sample docstring
# File: pyntcloud/core_class.py
# Example:
# def get_sample(self, sampler_name, **kwargs):
#     """
#     ...
#     Available samplers:
#     - your_new_sampler_alias: Description of what it does.
#     ...
#     """
#     pass

# 5. Document them in the Sphinx documentation
# File: docs/samplers.rst
# Example:
# .. autoclass:: pyntcloud.samplers.s_your_specific_sampler.YourSpecificSampler
#    :members:
```

--------------------------------

### Initialize PyntCloud from file and print attributes

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/PyntCloud.rst

This snippet demonstrates how to initialize a PyntCloud object by loading a point cloud from a file and then printing its representation, which includes information about points, faces, kdtrees, voxelgrids, centroid, and other attributes.

```Python
from pyntcloud import PyntCloud

cloud = PyntCloud.from_file("test/data/filters/filters.ply")

print(cloud)
```

--------------------------------

### Integrate PyntCloud with Open3D for Data Conversion

Source: https://github.com/daavoo/pyntcloud/blob/main/README.md

This snippet illustrates how to convert 3D data between Open3D and PyntCloud instances. It shows both converting an Open3D mesh to a PyntCloud object using `from_instance` and converting a PyntCloud object back to an Open3D mesh using `to_instance`.

```python
import open3d as o3d
from pyntcloud import PyntCloud

# FROM Open3D
original_triangle_mesh = o3d.io.read_triangle_mesh("diamond.ply")
cloud = PyntCloud.from_instance("open3d", original_triangle_mesh)

# TO Open3D
cloud = PyntCloud.from_file("diamond.ply")
converted_triangle_mesh = cloud.to_instance("open3d", mesh=True)  # mesh=True by default
```

--------------------------------

### Import PyntCloud Library

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This snippet imports the "PyntCloud" class from the "pyntcloud" library. This class is fundamental for creating and manipulating point cloud objects within the PyntCloud framework.

```python
from pyntcloud import PyntCloud
```

--------------------------------

### Run Pytest for Unit and Integration Tests

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/contributing.rst

Executes pytest with verbose output to run all defined tests for the pyntcloud project, ensuring the correctness and reliability of the codebase.

```bash
pytest -v
```

--------------------------------

### Visualize Sampled Point Cloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This code visualizes the sampled point cloud. The "return_scene=True" argument captures the visualization scene, which can then be reused to add more point clouds or elements to the same interactive plot.

```python
scene = anky_cloud.plot(return_scene=True)
```

--------------------------------

### Create Regular VoxelGrid by Number of Voxels

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Demonstrates how to create a regular VoxelGrid by specifying an equal number of voxels along each axis (e.g., 64x64x64). The generated VoxelGrid is then retrieved and plotted to visualize its density.

```python
voxelgrid_id = anky_cloud.add_structure("voxelgrid", n_x=64, n_y=64, n_z=64)

voxelgrid = anky_cloud.structures[voxelgrid_id]
```

```python
voxelgrid.plot(d=3, mode="density", cmap="hsv")
```

--------------------------------

### Load and Prepare 3D Point Cloud Data

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Loads a 3D mesh from a PLY file, visualizes it, then converts the mesh into a point cloud by sampling random points from its surface. The resulting point cloud is then visualized.

```python
anky = PyntCloud.from_file("data/ankylosaurus_mesh.ply")
anky
```

```python
anky.plot(mesh=True, backend="threejs")
```

```python
anky_cloud = anky.get_sample(
    "mesh_random", n=200000, rgb=True, normals=True, as_PyntCloud=True
)
```

```python
anky_cloud.plot()
```

--------------------------------

### Import core libraries for PyntCloud point cloud processing

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] Polylines.ipynb

This snippet imports `numpy` for numerical operations, `pandas` for data structuring, and `PyntCloud` from the `pyntcloud` library, which are foundational for creating and visualizing 3D point clouds.

```python
import numpy as np
import pandas as pd
from pyntcloud import PyntCloud
```

--------------------------------

### Create Regular VoxelGrid by Voxel Sizes

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Shows how to create a regular VoxelGrid by specifying an equal size for each voxel along all axes (e.g., 0.15 units). The generated VoxelGrid is then retrieved and plotted to visualize its uniform cell dimensions.

```python
voxelgrid_id = anky_cloud.add_structure(
    "voxelgrid", size_x=0.15, size_y=0.15, size_z=0.15
)

voxelgrid = anky_cloud.structures[voxelgrid_id]
```

```python
voxelgrid.plot(d=3, mode="density", cmap="hsv")
```

--------------------------------

### Generate Random Sample Point Cloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This code generates a new point cloud by randomly sampling 100 points from an existing point cloud. This smaller sample is created to demonstrate multi-point cloud visualization within a single scene.

```python
anky_cloud_sample = anky_cloud.get_sample("points_random", n=100, as_PyntCloud=True)
```

--------------------------------

### Plot Sample Point Cloud in Existing Scene

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This snippet plots the previously generated and colored sample point cloud within the existing visualization scene. By passing the "scene" object, it effectively combines multiple point clouds into a single interactive visualization.

```python
anky_cloud_sample.plot(initial_point_size=0.05, scene=scene)
```

--------------------------------

### Access VoxelGrid Information and Point-to-Voxel Mappings

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Demonstrates how to retrieve an existing VoxelGrid instance and access its properties, including the corresponding voxel coordinates (x, y, z) and a unique voxel number for each point in the original point cloud.

```python
voxelgrid_id = anky_cloud.add_structure("voxelgrid", n_x=64, n_y=64, n_z=64)

voxelgrid = anky_cloud.structures[voxelgrid_id]
```

```python
voxelgrid.voxel_x
```

```python
voxelgrid.voxel_y
```

```python
voxelgrid.voxel_z
```

```python
voxelgrid.voxel_n
```

--------------------------------

### Import Libraries for Point Cloud Processing

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Imports necessary libraries: NumPy for numerical operations and PyntCloud for point cloud manipulation.

```python
import numpy as np
```

```python
from pyntcloud import PyntCloud
```

--------------------------------

### Load 3D Mesh from File

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This code loads a 3D model of an ankylosaurus from a ".ply" file into a "PyntCloud" object. It demonstrates how to read point cloud data from a local file, making it ready for further processing or visualization.

```python
anky = PyntCloud.from_file("data/ankylosaurus_mesh.ply")
anky
```

--------------------------------

### Read Point Cloud from File using PyntCloud.from_file

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/io.rst

Demonstrates how to load a 3D point cloud from a specified file path using the PyntCloud.from_file method. This method automatically detects the file format and loads the data into a PyntCloud instance.

```python
from pyntcloud import PyntCloud
my_point_cloud = PyntCloud.from_file("some_file.ply")
```

--------------------------------

### Generate a random 3D point cloud with color attributes using NumPy and Pandas

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] Polylines.ipynb

This code creates a `PyntCloud` object by generating 1000 random 3D points and assigning random RGB color values. Point positions are centered, and data is structured in a pandas DataFrame before `PyntCloud` instantiation.

```python
positions = np.random.rand(1000, 3) * 10
positions -= positions.mean(0)

points = pd.DataFrame(positions.astype(np.float32), columns=["x", "y", "z"])

points["red"] = (np.random.rand(1000) * 255).astype(np.uint8)
points["green"] = (np.random.rand(1000) * 255).astype(np.uint8)
points["blue"] = (np.random.rand(1000) * 255).astype(np.uint8)

cloud = PyntCloud(points)
```

--------------------------------

### Plot Original Point Cloud and Capture Scene

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This code plots the original point cloud with a specified initial point size and captures the visualization scene. This scene object is crucial for subsequently adding other point clouds to the same interactive visualization.

```python
scene = anky_cloud.plot(initial_point_size=0.01, return_scene=True)
```

--------------------------------

### Sampler Base Class API Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers_dev.rst

All samplers in PyntCloud must inherit from this abstract base class. It defines the core structure and abstract methods (`extract_info`, `compute`) that all samplers must implement. Instances receive a PyntCloud object upon instantiation.

```APIDOC
Sampler:
  Inherits from: (Abstract Base Class)
  __init__(pyntcloud_instance: PyntCloud):
    pyntcloud_instance: The PyntCloud object to be sampled.
  Abstract Methods:
    extract_info():
      Description: Must be overridden to extract and save information required for sample generation.
    compute():
      Description: Generates and returns the sample, using information extracted by `extract_info`.
```

--------------------------------

### Import PyntCloud Library

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This snippet imports the `PyntCloud` class from the `pyntcloud` library. This class is fundamental for working with point cloud data, providing functionalities for loading, manipulating, and visualizing 3D data.

```python
from pyntcloud import PyntCloud
```

--------------------------------

### Visualize 3D Mesh with threejs Backend

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This snippet visualizes the loaded 3D mesh using the "plot" method. It explicitly sets "backend=\"threejs\"" as the mesh visualization is not supported by the default backend, which might affect compatibility in some environments.

```python
anky.plot(mesh=True, backend="threejs")
```

--------------------------------

### Create VoxelGrid Mixing Voxel Count and Size Parameters

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Illustrates how to create a VoxelGrid by combining both voxel count and size parameters. Note that size parameters override count parameters for the same axis. The generated VoxelGrid is then retrieved and plotted.

```python
voxelgrid_id = anky_cloud.add_structure(
    "voxelgrid",
    n_x=32,
    size_y=0.05,
    # n_z gets overrided by size_z and it'll be ignored
    n_z=2,
    size_z=0.01,
)

voxelgrid = anky_cloud.structures[voxelgrid_id]
```

```python
voxelgrid.plot(d=3, mode="density", cmap="hsv")
```

--------------------------------

### Create Irregular VoxelGrid by Voxel Sizes

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Demonstrates the creation of an irregular VoxelGrid by setting different sizes for voxels along each axis (e.g., 0.01x0.05x0.15 units). The resulting VoxelGrid is then retrieved and plotted to show its varied cell dimensions.

```python
voxelgrid_id = anky_cloud.add_structure(
    "voxelgrid", size_x=0.01, size_y=0.05, size_z=0.15
)

voxelgrid = anky_cloud.structures[voxelgrid_id]
```

```python
voxelgrid.plot(d=3, mode="density", cmap="hsv")
```

--------------------------------

### RandomMesh Sampler Class

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers.rst

Generates a sample by randomly selecting points from a mesh. This sampler requires 'pointcloud.mesh' to exist in the PyntCloud object.

```APIDOC
RandomMesh
```

--------------------------------

### Convert Mesh to Point Cloud by Random Sampling

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This code converts the 3D mesh into a point cloud by randomly sampling 100,000 points from its surface. It also extracts RGB colors and normal vectors for each sampled point, enriching the point cloud data.

```python
anky_cloud = anky.get_sample(
    "mesh_random", n=100000, rgb=True, normals=True, as_PyntCloud=True
)
```

--------------------------------

### VoxelgridCenters Sampler Class

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers.rst

Generates a sample using the centers of VoxelGrid cells. This sampler requires a VoxelGrid structure to be present in the point cloud.

```APIDOC
VoxelgridCenters
```

--------------------------------

### Create Irregular VoxelGrid by Number of Voxels

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Illustrates the creation of an irregular VoxelGrid by defining different numbers of voxels for each axis (e.g., 8x16x32). The resulting VoxelGrid is then retrieved and plotted to show its structure.

```python
voxelgrid_id = anky_cloud.add_structure("voxelgrid", n_x=8, n_y=16, n_z=32)

voxelgrid = anky_cloud.structures[voxelgrid_id]
```

```python
voxelgrid.plot(d=3, mode="density", cmap="hsv")
```

--------------------------------

### RandomPoints Sampler Class

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers.rst

Generates a sample by randomly selecting points from the original point cloud. This sampler requires points to be present in the input point cloud.

```APIDOC
RandomPoints
```

--------------------------------

### API Reference: PyntCloud.to_file

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/io.rst

Method for writing a PyntCloud instance to a specified file format. It allows specifying which internal components (e.g., 'points', 'mesh') to save.

```APIDOC
PyntCloud.to_file(filepath: str, internal: list = None, **kwargs)
  filepath: Path to the output file.
  internal: Optional list of strings specifying which internal components (e.g., "points", "mesh") to save. Defaults to saving all relevant components.
  **kwargs: Additional keyword arguments passed to the specific file writer.
```

--------------------------------

### Pyntcloud VoxelGrid Class API Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Comprehensive API documentation for the `VoxelGrid` class in `pyntcloud`. This reference details the available properties for accessing structural attributes of the voxel grid and the methods for querying point locations and extracting various types of feature vectors, including binary, density, and coordinate-based representations.

```APIDOC
VoxelGrid Properties:
  .x_y_z: tuple (int, int, int)
    Description: Number of voxels along the X, Y, and Z axes.
  .n_voxels: int
    Description: Total number of voxels in the grid.
  .shape: tuple (int, int, int)
    Description: Shape of the voxel grid (equivalent to x_y_z).
  .segments: tuple (np.ndarray, np.ndarray, np.ndarray)
    Description: Minimum and maximum coordinates of each voxel per axis (min_max_x, min_max_y, min_max_z).
  .voxel_centers: np.ndarray
    Description: Coordinates of the center of each voxel.

VoxelGrid Methods:
  .query(points: np.ndarray) -> np.ndarray
    Description: Finds the voxel index for each given point.
    Parameters:
      points (np.ndarray): An array of 3D points to query.
    Returns:
      np.ndarray: An array of voxel indices corresponding to each input point.

  .get_feature_vector(mode: str) -> np.ndarray
    Description: Returns a 3D array representing the VoxelGrid based on the specified mode.
    Parameters:
      mode (str): The type of feature vector to extract.
        "binary": Returns 0s for empty voxels, 1s for occupied voxels.
        "density": Returns normalized percentage of points in each voxel (0-1).
        "x_max": Returns the maximum X coordinate value inside each voxel.
        "y_max": Returns the maximum Y coordinate value inside each voxel.
        "z_max": Returns the maximum Z coordinate value inside each voxel.
        "x_mean": Returns the mean X coordinate value inside each voxel.
        "y_mean": Returns the mean Y coordinate value inside each voxel.
        "z_mean": Returns the mean Z coordinate value inside each voxel.
    Returns:
      np.ndarray: A 3D NumPy array representing the feature vector.
```

--------------------------------

### Define and plot basic 3D coordinate axis polylines

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] Polylines.ipynb

This snippet defines three simple polylines representing the X, Y, and Z axes with distinct colors (red, green, blue) and two vertices each. These polylines are then passed to the `cloud.plot()` method for visualization alongside the point cloud.

```python
lines = [
    {"color": "red", "vertices": [[0, 0, 0], [10, 0, 0]]},
    {"color": "green", "vertices": [[0, 0, 0], [0, 10, 0]]},
    {"color": "blue", "vertices": [[0, 0, 0], [0, 0, 10]]}
]
```

```python
cloud.plot(polylines=lines)
```

--------------------------------

### Sampler_Voxelgrid Submodule Base Class API Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers_dev.rst

This class serves as a base for samplers that require a VoxelGrid for computation. It overrides the `__init__` and `extract_info` methods of the `Sampler` base class to handle VoxelGrid-specific information extraction. Developers should create new submodule base classes if their sampler needs different information.

```APIDOC
Sampler_Voxelgrid:
  Inherits from: Sampler
  Overrides:
    __init__(pyntcloud_instance: PyntCloud, ...):
      Description: Initializes the sampler, handling VoxelGrid-specific parameters.
    extract_info():
      Description: Extracts and saves VoxelGrid-related information.
```

--------------------------------

### Visualize Point Cloud with Custom Scalar Field and Colormap

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This snippet visualizes the point cloud by coloring points based on a custom scalar field, specifically the 'x' coordinate. It applies the 'cool' Matplotlib colormap, allowing for data-driven colorization based on point attributes.

```python
anky_cloud.plot(use_as_color="x", cmap="cool")
```

--------------------------------

### PyntCloud.get_sampler Method API Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers_dev.rst

This method is used to retrieve samplers within the PyntCloud library. Developers should consult its source code to understand how samplers are utilized.

```APIDOC
PyntCloud.get_sampler()
```

--------------------------------

### Calculate and Visualize Planarity with Pyntcloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

Demonstrates how to compute the planarity scalar field for a point cloud using `anky_cloud.add_scalar_field` and then visualize its distribution with a histogram and color the point cloud based on its values.

```python
planarity = anky_cloud.add_scalar_field("planarity", ev=eigenvalues)
anky_cloud.points[planarity].plot(kind="hist");
anky_cloud.plot(use_as_color=planarity, cmap="jet")
```

--------------------------------

### VoxelgridNearest Sampler Class

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers.rst

Generates a sample by selecting the nearest point to the center of each occupied VoxelGrid cell. This sampler requires a VoxelGrid structure to be present in the point cloud.

```APIDOC
VoxelgridNearest
```

--------------------------------

### Visualize 3D Mesh with PyntCloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This snippet visualizes the loaded 3D mesh using the `plot` method of the `PyntCloud` object. It specifies `mesh=True` to render the mesh and `backend="threejs"` as the visualization backend, which is required for mesh plotting. This allows for interactive exploration of the 3D model.

```python
anky.plot(mesh=True, backend="threejs")
```

--------------------------------

### VoxelgridCentroids Sampler Class

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/samplers.rst

Generates a sample by computing the centroid of points within each occupied VoxelGrid cell. This sampler requires a VoxelGrid structure to be present in the point cloud.

```APIDOC
VoxelgridCentroids
```

--------------------------------

### Load 3D Mesh from File using PyntCloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This code loads a 3D mesh model of an ankylosaurus from a specified file path using `PyntCloud.from_file()`. The loaded object, `anky`, represents the mesh and can be further processed or visualized. It demonstrates how to initialize a PyntCloud object from an existing file.

```python
anky = PyntCloud.from_file("data/ankylosaurus_mesh.ply")
anky
```

--------------------------------

### Import PyntCloud Library

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] normals.ipynb

Imports the necessary `PyntCloud` class from the `pyntcloud` library, which is essential for working with point cloud data and 3D models.

```python
from pyntcloud import PyntCloud
```

--------------------------------

### KDTree Structure Class

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/structures.rst

The `KDTree` class provides a K-dimensional tree structure, optimized for efficient nearest neighbor searches and range queries within a point cloud. It significantly speeds up spatial queries on large datasets.

```APIDOC
class KDTree:
```

--------------------------------

### API Reference: PyntCloud.from_file

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/io.rst

Method for reading 3D point cloud data from various file formats. It supports common formats like .ply, .obj, .las, .pcd, .off, .npy, .npz, and ASCII files (.asc, .pts, .txt, .csv, .xyz). For ASCII files, it internally calls `pandas.read_csv` and accepts its keyword arguments for flexible parsing (e.g., `sep`, `header`, `names`).

```APIDOC
PyntCloud.from_file(filepath: str, **kwargs)
  filepath: Path to the input file.
  **kwargs: Additional keyword arguments passed to internal readers (e.g., pandas.read_csv for ASCII files).
```

--------------------------------

### Create VoxelGrid with Irregular Bounding Box

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

Shows how to create a VoxelGrid where the bounding box is not forced to be regular, allowing the voxel grid to adapt to the point cloud's natural extent. This results in potentially non-uniform voxel shapes. The resulting VoxelGrid's shape property is also accessed.

```python
voxelgrid_id = anky_cloud.add_structure(
    "voxelgrid", n_x=64, n_y=64, n_z=64, regular_bounding_box=False
)

voxelgrid = anky_cloud.structures[voxelgrid_id]
```

```python
voxelgrid.plot(d=3, mode="density", cmap="hsv")
```

```python
voxelgrid.shape
```

--------------------------------

### Read Custom ASCII Point Cloud File with PyntCloud.from_file

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/io.rst

Shows how to read an ASCII point cloud file (e.g., .pts) that might have a custom format. PyntCloud.from_file internally uses pandas.read_csv for ASCII files, allowing users to pass keyword arguments like 'sep', 'header', and 'names' to correctly parse the data based on its structure.

```python
import pandas as pd
from pyntcloud import PyntCloud

cloud = PyntCloud.from_file("example.pts",
                                sep=" ",
                                header=0,
                                names=["x","y","z"])
```

--------------------------------

### Calculate and Visualize Sphericity with Pyntcloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

Demonstrates how to compute the sphericity scalar field for a point cloud using `anky_cloud.add_scalar_field` and then visualize its distribution with a histogram and color the point cloud based on its values.

```python
sphericity = anky_cloud.add_scalar_field("sphericity", ev=eigenvalues)
anky_cloud.points[sphericity].plot(kind="hist");
anky_cloud.plot(use_as_color=sphericity, cmap="jet")
```

--------------------------------

### Visualize Sampled Point Cloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This code visualizes the sampled point cloud (`anky_cloud`) using the `plot()` method. This generates an interactive 3D plot of the points, allowing users to adjust background color and point size. It provides a quick way to inspect the generated point cloud data.

```python
anky_cloud.plot()
```

--------------------------------

### Delaunay3D Structure Class

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/structures.rst

The `Delaunay3D` class implements the 3D Delaunay triangulation for a point cloud. This structure is useful for spatial analysis, mesh generation, and understanding the topological relationships between points.

```APIDOC
class Delaunay3D:
```

--------------------------------

### Calculate and Visualize Omnivariance with Pyntcloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

Demonstrates how to compute the omnivariance scalar field for a point cloud using `anky_cloud.add_scalar_field` and then visualize its distribution with a histogram and color the point cloud based on its values.

```python
omnivariance = anky_cloud.add_scalar_field("omnivariance", ev=eigenvalues)
anky_cloud.points[omnivariance].plot(kind="hist");
anky_cloud.plot(use_as_color=omnivariance, cmap="jet")
```

--------------------------------

### PyntCloud.add_structure Function

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/structures.rst

This function is used to add various structures to a `PyntCloud` instance, enabling advanced operations and analyses on the point cloud data. It serves as the primary entry point for integrating structural enhancements.

```APIDOC
PyntCloud.add_structure()
```

--------------------------------

### Convert Mesh to Point Cloud by Random Sampling

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This code converts the 3D mesh into a point cloud by randomly sampling 100,000 points from its surface using `get_sample()`. It also extracts RGB colors and surface normals for each sampled point, creating a new `PyntCloud` object named `anky_cloud`. This is useful for transforming mesh data into a point cloud representation for further analysis.

```python
anky_cloud = anky.get_sample(
    "mesh_random", n=100000, rgb=True, normals=True, as_PyntCloud=True
)
```

--------------------------------

### PyntCloud.get_filter Method Reference

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/filters.rst

This API reference describes the PyntCloud.get_filter method, which serves as the entry point for accessing various filtering functionalities within a PyntCloud object. Filters are categorized based on their computational requirements.

```APIDOC
PyntCloud.get_filter()
```

--------------------------------

### Set RGB Color for Sample Point Cloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This snippet manually sets the RGB color components for the newly sampled point cloud to pure red (255, 0, 0). This ensures the sample is visually distinct and easily identifiable when plotted alongside other point clouds.

```python
anky_cloud_sample.points["red"] = 255
anky_cloud_sample.points["green"] = 0
anky_cloud_sample.points["blue"] = 0
```

--------------------------------

### Visualize Point Cloud Colored by Curvature

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This snippet visualizes the point cloud, coloring each point based on its curvature value using a 'jet' colormap. The `use_as_color` argument maps the scalar field to the point color, providing a visual representation of how curvature varies across the 3D model. This helps in identifying regions with different surface bending characteristics.

```python
anky_cloud.plot(use_as_color=curvature, cmap="jet")
```

--------------------------------

### Visualize Point Cloud Colored by Sum of Eigenvalues

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This snippet visualizes the point cloud, coloring each point based on its sum of eigenvalues using a 'jet' colormap. The `use_as_color` argument maps the scalar field to the point color, providing a visual representation of how the sum of eigenvalues varies across the 3D model. This helps in identifying regions with different local density characteristics.

```python
anky_cloud.plot(use_as_color=eigensum, cmap="jet")
```

--------------------------------

### Instantiating PyntCloud without XYZ Columns (Incorrect)

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/points.rst

This snippet shows an attempt to create a `PyntCloud` from a pandas DataFrame that lacks 'x', 'y', and 'z' columns. This demonstrates another restriction: the DataFrame used for `points` must contain these specific coordinate columns, leading to a `ValueError`.

```python
import numpy as np

import pandas as pd

from pyntcloud import PyntCloud

points = pd.DataFrame(np.random.rand(1000, 3))

cloud = PyntCloud(points)
```

--------------------------------

### Access VoxelGrid Structural Properties

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[structures] VoxelGrid.ipynb

This snippet demonstrates how to retrieve fundamental structural information from a `VoxelGrid` object in `pyntcloud`. It covers accessing the number of voxels per axis, total voxel count, grid shape, minimum and maximum coordinates of voxel segments, and the coordinates of voxel centers. These properties are essential for understanding the voxelization output.

```python
voxelgrid.x_y_z
```

```python
voxelgrid.n_voxels
```

```python
voxelgrid.shape
```

```python
min_max_x, min_max_y, min_max_z = voxelgrid.segments
```

```python
min_max_x
```

```python
voxelgrid.voxel_centers
```

--------------------------------

### Visualize Sampled Point Cloud with PyntCloud

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] normals.ipynb

Visualizes the newly created point cloud, `anky_cloud`, using the default `plot` method. This provides a visual representation of the sampled points, allowing for inspection of the point cloud's structure.

```python
anky_cloud.plot()
```

--------------------------------

### Initialize KDTree for PyntCloud Filters

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/filters.rst

This Python snippet demonstrates how to initialize a KDTree structure within a PyntCloud object. A KDTree is essential for efficient nearest neighbor searches required by certain filters, such as Radius Outlier Removal (ROR) and Statistical Outlier Removal (SOR).

```python
kdtree = pointcloud.add_structure("kdtree", ...)
```

--------------------------------

### Visualize Point Cloud Colored by Inclination (Radians)

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] normals.ipynb

Visualizes the point cloud, coloring each point based on its calculated inclination in radians. A 'jet' colormap is used to represent the range of inclination values, providing an intuitive visual representation of the surface's varying slopes.

```python
anky_cloud.plot(use_as_color=inclination_radians, cmap="jet")
```

--------------------------------

### Visualize Point Cloud Colored by Linearity

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This snippet visualizes the point cloud, coloring each point based on its linearity value using a 'jet' colormap. The `use_as_color` argument maps the scalar field to the point color, providing a visual representation of how linearity varies across the 3D model. This helps in identifying regions with different local linearity characteristics.

```python
anky_cloud.plot(use_as_color=linearity, cmap="jet")
```

--------------------------------

### PyntCloud.get_filter Method Usage

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/filters_dev.rst

This method is used by `PyntCloud` instances to apply filters. Developers should examine its source code in `pyntcloud/core_class.py` to understand how filters are integrated and used within the `PyntCloud` framework.

```APIDOC
PyntCloud.get_filter()
```

--------------------------------

### Visualize Point Cloud Normals using Pandas Built-in Plotting

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[visualization] PyntCloud.ipynb

This snippet leverages Pandas' built-in visualization capabilities to plot a histogram of the normal components (nx, ny, nz) of the sampled point cloud. It demonstrates how to access and visualize the underlying DataFrame data within a "PyntCloud" object.

```python
anky_cloud.points[["nx", "ny", "nz"]].plot(kind="hist", subplots=True);
```

--------------------------------

### Visualize Point Cloud Colored by Eigenentropy

Source: https://github.com/daavoo/pyntcloud/blob/main/examples/[scalar_fields] eigenvalues.ipynb

This snippet visualizes the point cloud, coloring each point based on its eigenentropy value using a 'jet' colormap. The `use_as_color` argument maps the scalar field to the point color, providing a visual representation of how eigenentropy varies across the 3D model. This helps in identifying regions with different levels of local disorder.

```python
anky_cloud.plot(use_as_color=eigenentropy, cmap="jet")
```

--------------------------------

### Base Filter Class (pyntcloud.filters.base.Filter)

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/filters_dev.rst

The abstract base class for all filters in `pyntcloud`. All custom filters must inherit from this class and implement its core methods: `__init__` for instantiation, `extract_info` for pre-computation data extraction, and `compute` for generating the boolean filter array.

```APIDOC
class Filter:
  __init__(self, pyntcloud_instance: PyntCloud)
    pyntcloud_instance: The PyntCloud instance to which the filter will be applied.
  extract_info(self) -> None
    Purpose: Abstract method to extract and save information required to compute the filter.
    This information should be stored as an attribute of the filter instance.
  compute(self) -> numpy.ndarray[bool]
    Purpose: Abstract method where the boolean array for filtering is generated and returned.
    It should use the information extracted by `extract_info`.
```

--------------------------------

### Generating Box Plot for PyntCloud Points

Source: https://github.com/daavoo/pyntcloud/blob/main/docs/points.rst

This snippet demonstrates how to visualize the distribution of point coordinates using a box plot. It leverages the `boxplot()` method available on the pandas DataFrame representing the `points` attribute.

```python
cloud.points.boxplot()
```