sphractal.surfVoxel

Module Contents

Functions

fibonacciSphere(numPoints, sphereRad)	Generate evenly spread points on the surface of a sphere with a specified radius.
withinNeighRad(surfPointXYZ, atomNeighIdxs, atomsRad, ...)	Return whether a surface point generated around a given atom falls within the radius of a neighbouring atom.
rmPoint(args)	Check whether a point falls on the outer surface.
pointsOnAtom(args)	Generate surface points around an atom and classify them as either inner or outer surface.
pointsToVoxels(pointXYZs, gridSize)	Turn coordinates of point clouds into coordinates of occupied voxels.
writeSurfVoxelIdxs(outDir, voxelIdxs)	Generate a txt file required for 3D box-counting using C++ code written by Ruiz de Miras and Posadas.
writePCD(outDir, npName, surfPointXYZs)	Generate a pcd file required for 3D box-counting using MATLAB code written by Kazuaki Iida.
writeSurfPoints(outDir, npName, atomsSurfIdxs, ...)	Generate an xyz file for visualisation of classified point clouds.
writeSurfVoxels(outDir, npName, surfVoxelXYZs)	Generate an xyz file useful for visualisation of computed surface voxels.
genSurfPoints(atomsEle, atomsRad, atomsSurfIdxs, ...)	Generate point clouds approximating the outer spherical surface formed by a set of atoms.
voxelBoxCnts(atomsEle, atomsRad, atomsSurfIdxs, ...[, ...])	Count the boxes that cover the outer surface of a set of overlapping spheres represented as point clouds for different box sizes, using 3D box-counting algorithm written by Ruiz de Miras et al. in C++.

sphractal.surfVoxel.fibonacciSphere(numPoints, sphereRad)

Generate evenly spread points on the surface of a sphere with a specified radius.

sphractal.surfVoxel.withinNeighRad(surfPointXYZ, atomNeighIdxs, atomsRad, atomsXYZ)

Return whether a surface point generated around a given atom falls within the radius of a neighbouring atom.

sphractal.surfVoxel.rmPoint(args)

Check whether a point falls on the outer surface.

sphractal.surfVoxel.pointsOnAtom(args)

Generate surface points around an atom and classify them as either inner or outer surface.

sphractal.surfVoxel.pointsToVoxels(pointXYZs, gridSize)

Turn coordinates of point clouds into coordinates of occupied voxels.

sphractal.surfVoxel.writeSurfVoxelIdxs(outDir, voxelIdxs)

Generate a txt file required for 3D box-counting using C++ code written by Ruiz de Miras and Posadas.

sphractal.surfVoxel.writePCD(outDir, npName, surfPointXYZs)

Generate a pcd file required for 3D box-counting using MATLAB code written by Kazuaki Iida.

sphractal.surfVoxel.writeSurfPoints(outDir, npName, atomsSurfIdxs, atomsXYZ, surfPointXYZs, nonSurfPointXYZs)

Generate an xyz file for visualisation of classified point clouds.

sphractal.surfVoxel.writeSurfVoxels(outDir, npName, surfVoxelXYZs)

Generate an xyz file useful for visualisation of computed surface voxels.

sphractal.surfVoxel.genSurfPoints(atomsEle, atomsRad, atomsSurfIdxs, atomsXYZ, atomsNeighIdxs, npName, outDir='outputs', numCPUs=None, radType='atomic', numPoints=10000, gridNum=1024, rmInSurf=True, vis=False, verbose=False, genPCD=False)

Generate point clouds approximating the outer spherical surface formed by a set of atoms.

sphractal.surfVoxel.voxelBoxCnts(atomsEle, atomsRad, atomsSurfIdxs, atomsXYZ, atomsNeighIdxs, npName, outDir='outputs', numCPUs=None, exePath='$FASTBC', radType='atomic', numPoints=300, gridNum=1024, rmInSurf=True, vis=True, verbose=False, genPCD=False)

Count the boxes that cover the outer surface of a set of overlapping spheres represented as point clouds for different box sizes, using 3D box-counting algorithm written by Ruiz de Miras et al. in C++.

IMPORTANT: Make sure the source code has been downloaded from https://github.com/Jon-Ting/fastBC and compiled on your machine. ‘exePath’ should point to the right directory if FASTBC is not set as an environment variable.

Parameters:

• atomsEle (1D ndarray of strs) – Element type of each atom.

• atomsRad (1D ndarray of floats) – Radius of each atom.

• atomsSurfIdxs (1D ndarray of ints) – Indices of surface atoms.

• atomsXYZ (2D ndarray of floats) – Cartesian coordinates of each atom.

• atomsNeighIdxs (2D ndarray of ints) – Neighbour atoms indices of each atom.

• npName (str) – Identifier of the measured object, which forms part of the output file name, ideally unique.

• outDir (str, optional) – Path to the directory to store the output files.

• numCPUs (int, optional) – Number of CPUs to be used for parallelisation of tasks.

• exePath (str, optional) – Path to the compiled C++ executable for box-counting.

• radType ({'atomic', 'metallic'}, optional) – Type of radii to use for the spheres.

• numPoints (int, optional) – Number of surface points to be generated around each atom.

• gridNum (int, optional) – Resolution of the 3D binary image.

• rmInSurf (bool, optional) – Whether to remove the surface points on the inner surface.

• vis (bool, optional) – Whether to generate output files for visualisation.

• verbose (bool) – Whether to display the details.

• genPCD (bool, optional) – Whether to generate pcd file for box-counting using MATLAB code written by Kazuaki Iida.

Returns:

• scales (list) – Box lengths.

• counts (list) – Number of boxes that cover the surface of interest, as represented by the voxels in the 3D binary image.

Examples

>>> eles, rads, xyzs, _, minxyz, maxxyz = readInp('example.xyz')
>>> neighs, _ = findNN(rads, xyzs, minxyz, maxxyz, 1.2)
>>> surfs = findSurf(xyzs, neighs, 'alphaShape', 5.0)
>>> scalesPC, countsPC = voxelBoxCnts(eles, rads, surfs, xyzs, neighs, 'example')

Notes

The 3D binary image resolution (gridNum) is restricted to 1024 or lower. Details about maximum grid size and memory estimation could be found in ‘test.cpp’ documented by the authors (https://www.ugr.es/~demiras/fbc/).