dotty documentation
===================
A C23 library for simple manipulations of point clouds that represent 2D surfaces embedded in 3D space.

It is bundled with small applications that can be useful when scripting.
Since point clouds contain not connectivity and the points are mutually independent, the provided applications process files on a line-by-line basis.
This saves memory compared to reading the entire file into memory, processing it, then writing it back out.

.. default-domain:: c

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Data Structures
===============
.. doxygenenum:: dotty_axis
.. doxygenenum:: dotty_axis_pair

.. doxygenstruct:: dotty_vector
    :members:

.. doxygenstruct:: dotty_eigenvector
    :members:

.. doxygenstruct:: dotty_aa_bounding_box
    :members:

.. doxygenstruct:: dotty_point
    :members:

.. doxygenstruct:: dotty_pointcloud
    :members:

.. doxygenstruct:: dotty_aa_rotation_matrix
    :members:

Functions
=========

.. doxygenfunction:: dotty_add_vectors
.. doxygenfunction:: dotty_subtract_vectors
.. doxygenfunction:: dotty_normalise_vector
.. doxygenfunction:: dotty_angle
.. doxygenfunction:: dotty_cross_product
.. doxygenfunction:: dotty_dot_product
.. doxygenfunction:: dotty_compute_modulus
.. doxygenfunction:: dotty_compute_separation

.. doxygenfunction:: dotty_create_aa_rotation_matrix
.. doxygenfunction:: dotty_aa_rotate_vector

.. doxygenfunction:: dotty_free_pointcloud
.. doxygenfunction:: dotty_copy_pointcloud
.. doxygenfunction:: dotty_translate_pointcloud
.. doxygenfunction:: dotty_swap_pointcloud_coordinates
.. doxygenfunction:: dotty_scale_pointcloud
.. doxygenfunction:: dotty_compute_pointcloud_aabb
.. doxygenfunction:: dotty_aa_rotate_pointcloud

.. doxygenfunction:: dotty_count_points
.. doxygenfunction:: dotty_detect_normals
.. doxygenfunction:: dotty_translate_pc_file
.. doxygenfunction:: dotty_swap_pc_file_coordinates
.. doxygenfunction:: dotty_scale_pc_file
.. doxygenfunction:: dotty_compute_pc_file_aabb
.. doxygenfunction:: dotty_convert_bnpts_file_to_ascii

.. doxygenfunction:: dotty_generate_plane
.. doxygenfunction:: dotty_generate_sphere
.. doxygenfunction:: dotty_generate_torus
.. doxygenfunction:: dotty_generate_cube
.. doxygenfunction:: dotty_generate_bulbous
.. doxygenfunction:: dotty_generate_cone

.. doxygenfunction:: dotty_open_mandatory_file
.. doxygenfunction:: dotty_compare_eigenvectors


Applications
============

.. describe:: dotty-size

    ``dotty-size <file-to-test>`` - print the dimensions of the axis-aligned bounding box of a point cloud.

.. describe:: dotty-scale

    ``dotty-scale <scale-factor> <infile> <outfile>`` - scale a point cloud by the provided scale factor (``<1.0`` is shrinking, ``>1.0`` is growth).

.. describe:: dotty-translate

    ``dotty-translate <infile> <outfile> <xshift> <yshift> <zshift>`` - shift the position of a point cloud by the specified amounts (which can be ``0``).

.. describe:: dotty-swap-axes

    ``dotty-swap-axes <infile> <outfile> <"xy" swap>`` - swap the axes of a point cloud, e.g. swap the ``x`` and ``y`` axes.

.. describe:: dotty-generate-analytic

    ``dotty-generate-analytic`` - create a set of point clouds (with and without normals) of a plane, sphere, torus, cube, cone, and an eight-lobed shape, the name of which I don't know!

.. describe:: dotty-bnpts2npts

    ``dotty-bnpts2npts <input bnpts> <output npts>`` - convert a binary ``.bnpts`` file into a plaintext ``.npts`` file (same as a ``.xyz`` file).