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.

Data Structures

enum dotty_axis

Cartesian (x/y/z) axes.

Values:

enumerator X_Axis

enumerator Y_Axis

enumerator Z_Axis

enum dotty_axis_pair

A pair of Cartesian axes.

Values:

enumerator x_y

enumerator x_z

enumerator y_z

struct dotty_vector: A vector in 3D.

struct dotty_eigenvector: An eigenvector with its corresponding eigenvalue.

struct dotty_aa_bounding_box: An axis-aligned bounding box - its members correspond to the component-wise maximum/minimum observed position of any point in a cloud.

struct dotty_point: A point on a 2D surface embedded in 3D space. Whether the normal is meaningful must be determined by the containing dotty_pointcloud.

struct dotty_pointcloud: A set of points in 3D space that represent a 2D surface. For example, the surface of a balloon. The points may or may not have associated normals that indicate the gradient to the surface at that point. If they do not, has_normals will be false and the normal member of each constituent point will not be meaningful. NB: It is required that all points have normals or no points do.

struct dotty_aa_rotation_matrix

A matrix representing a rotation around axis of dotty_angle radians.

Public Members

dotty_axis axis: Axis around which to rotate.

double dotty_angle: Angle (in radians) by which to rotate.

double elements[3][3]: Elements of the rotation matrix.

Functions

dotty_vector dotty_add_vectors(dotty_vector a, dotty_vector b): Return the result of a + b.

dotty_vector dotty_subtract_vectors(dotty_vector a, dotty_vector b): Return the result of a - b.

void dotty_normalise_vector(dotty_vector *a): Whilst keeping the relative size of its components the same, adjust the magnitude of A to 1.0. If A has a magnitude of 0.0, this function has no effect.

double dotty_angle(dotty_vector a, dotty_vector b): Compute the dotty_angle between two vectors, range [0, M_PI].

dotty_vector dotty_cross_product(dotty_vector a, dotty_vector b): Return the cross product of a and b (a x b, or a ^ b). Note that the cross product is not commutative: a x b == -b x a.

double dotty_dot_product(dotty_vector a, dotty_vector b): Dot/inner product of a and b.

double dotty_compute_modulus(dotty_vector a): Return the modulus of a.

double dotty_compute_separation(dotty_vector a, dotty_vector b): Compute the straight-line (Euclidean) distance between a and b.

dotty_aa_rotation_matrix dotty_create_aa_rotation_matrix(dotty_axis axis, double angle_in_radians): Create a matrix that represents a rotation around axis of the specified number of radians. The dotty_angle is stored directly, not modulo 2*M_PI.

dotty_vector dotty_aa_rotate_vector(const dotty_aa_rotation_matrix *rm, dotty_vector v): Apply the rotation represented by rm to vector v.

void dotty_free_pointcloud(dotty_pointcloud *pc): Free the memory associated with a point cloud and, to keep the other members consistent, reset them as though newly defined by dotty_pointcloud pc = {};.

bool dotty_copy_pointcloud(const dotty_pointcloud *src_pc, dotty_pointcloud *dst_pc): Deep-copy src_pc pointcloud to dst_pc pointcloud. Since this is a deep copy, the .points members will not be equal, but will nevertheless point to memory that contains the same data.

void dotty_translate_pointcloud(dotty_pointcloud *pc, dotty_vector translation): Update the position of each point in the cloud by adding translation.

void dotty_swap_pointcloud_coordinates(dotty_pointcloud *pc, dotty_axis_pair coordinates): Swap the provided coordinates of each point in the cloud.

void dotty_scale_pointcloud(dotty_pointcloud *pc, double scale_factor): Scale the position of each point in a cloud by the provided scale_factor. A scale factor =1.0 causes no change, >1 causes growth, and <1 causes shrinkage.

dotty_aa_bounding_box dotty_compute_pointcloud_aabb(const dotty_pointcloud *pc): Compute the axis-aligned bounding box of a point cloud.

void dotty_aa_rotate_pointcloud(dotty_pointcloud *pc, const dotty_aa_rotation_matrix *rm): Apply the rotation encoded in rm to the point cloud pc.

uint32_t dotty_count_points(const char *pc_filename): Return the number of points in a point cloud file. Raises SIGABRT if the file cannot be opened.

bool dotty_detect_normals(const char *pointcloud_filename): Return true if the point cloud file contains normal data. The heuristic used is the number of items on the first line of the file. 3 items => only positions, 6 items => positions and normals. Raises SIGABRT if the file cannot be opened.

bool dotty_translate_pc_file(const char *input_name, const char *output_name, dotty_vector translation): Update the position of each point in the file by adding translation. Returns false if there was an error.

bool dotty_swap_pc_file_coordinates(const char *input_filename, const char *output_filename, dotty_axis_pair coordinates): Returns false if there was an error.

bool dotty_scale_pc_file(const char *input_filename, const char *output_filename, double scale_factor): Scale the position of each point in a file by the provided scale_factor. A scale factor =1.0 causes no change, >1 causes growth, and <1 causes shrinkage. Returns false if there was an error.

dotty_aa_bounding_box dotty_compute_pc_file_aabb(const char *input_filename): Compute the axis-aligned bounding box of a point cloud file. Raises SIGABRT if there was an error reading the input file.

bool dotty_convert_bnpts_file_to_ascii(const char *input_filename, const char *output_filename): Returns false if there was an error.

void dotty_generate_plane(const char *without_normals, const char *with_normals, double principal_size): Create a square set of points laying in th z=0 plane. The extents are from -principal_size/2 to +principal_size/2. The points are placed in a deterministic manner.

void dotty_generate_sphere(const char *without_normals, const char *with_normals, double radius): Create a point cloud of a sphere of radius principal_size, centred on the origin. The points are placed in a deterministic manner.

void dotty_generate_torus(const char *without_normals, const char *with_normals, double outer_radius, double inner_radius): Create a toroidal point cloud laying in the z=0 plane. The outer_radius is of the ‘doughnut’, and inner_radius is of the ‘tube’. The points are placed in a deterministic manner.

void dotty_generate_cube(const char *without_normals, const char *with_normals, double side_length): Create a cube point cloud, centred on the origin. The points are placed randomly with one face, then mirrored to the others.

void dotty_generate_bulbous(const char *without_normals, const char *with_normals, double principal_size): Create a point cloud that has eight ‘lobes’ that meet in the centre. This probably has a name, but I don’t know what it is! The points are placed in a deterministic manner.

void dotty_generate_cone(const char *without_normals, const char *with_normals, double base_radius, double height): Generate point cloud of a code, with base laying in the z=0 plane and centered on the origin. The peak extends to a maximum value at (0, 0, height). The points are placed in a deterministic manner.

FILE *dotty_open_mandatory_file(const char *filename, const char *mode): Wraps fopen, raising SIGABRT rather than returning nullptr on errors.

int dotty_compare_eigenvectors(const void *first, const void *second): Compares two eigenvectors by the magnitude of their eigenvalues. Returns 1 if the eigenvalue of first > eigenvalue of second, or -1 if the reverse. If both somehow compare equal, returns 0.

Applications

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

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).

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

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.

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!

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