gaara 0.1.0__tar.gz

gaara-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Linker files
+*.ilk
+
+# Debugger Files
+*.pdb
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+*.so.*
+
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+# Build directories
+build/
+Build/
+build-*/
+
+# CMake generated files
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+Makefile
+install_manifest.txt
+compile_commands.json
+
+# Temporary files
+*.tmp
+*.log
+*.bak
+*.swp
+
+# vcpkg
+vcpkg_installed/
+
+# debug information files
+*.dwo
+
+# test output & cache
+Testing/
+.cache/

gaara-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, William Silversmith
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

gaara-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: gaara
+Version: 0.1.0
+Summary: Skeleton generation via 3D voxel thinning.
+License-Expression: BSD-3-Clause
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: numpy
+

gaara-0.1.0/README.md

@@ -0,0 +1,29 @@
+# gaara
+Skeleton thinning algorithm for large images.
+
+```python
+import gaara
+import numpy as np
+
+arr = np.load(...) # some 3d array in fortran order
+
+# binary images are slightly more efficient to process
+# 80% of the memory and slightly faster.
+
+arr = gaara.skeletonize(arr, binary_image=True, in_place=False)
+arr = gaara.skeletonize(arr, binary_image=False, in_place=False)
+```
+
+Gaara is a skeletion generation via voxel thinning algorithm based on Palágyi's 2014 paper [1] and inspired by Matejek et al.'s work on [synapseaware](https://github.com/Rhoana/synapseaware/). [2]
+
+While efficient and fine for tracing neurites that have a natural tree structure, a shortcoming of [Kimimaro](https://github.com/seung-lab/kimimaro) is its inability to generate topologically correct skeletons [3] which have applications to e.g. glia and blood vessels.
+
+Gaara attempts to be an efficient voxel thinning algorithm implementation that can handle very large images on a single machine by making use of crackle compression dynamically.
+
+## References
+
+1. K. Palágyi et al., “A Sequential 3D Thinning Algorithm and Its Medical Applications,” in Information Processing in Medical Imaging, M. F. Insana and R. M. Leahy, Eds., Berlin, Heidelberg: Springer, 2001, pp. 409–415. doi: 10.1007/3-540-45729-1_42.  
+
+2. B. Matejek, D. Wei, X. Wang, J. Zhao, K. Palágyi, and H. Pfister, “Synapse-Aware Skeleton Generation for Neural Circuits,” in Medical Image Computing and Computer Assisted Intervention – MICCAI 2019, D. Shen, T. Liu, T. M. Peters, L. H. Staib, C. Essert, S. Zhou, P.-T. Yap, and A. Khan, Eds., Cham: Springer International Publishing, 2019, pp. 227–235. doi: 10.1007/978-3-030-32239-7_26.  
+
+3. T. A. Syed, M. Youssef, A. L. Schober, Y. Kubota, K. K. Murai, and C. K. Salmon, “Beyond Neurons: Computer Vision Methods for Analysis of Morphologically Complex Astrocytes,” Frontiers in Computer Science, vol. 6, Sep. 2024, doi: 10.3389/fcomp.2024.1156204.  

gaara-0.1.0/gaara/__init__.py

@@ -0,0 +1,49 @@
+import numpy as np
+import numpy.typing as npt
+
+from . import fastgaara
+
+__all__ = ["skeletonize"]
+
+def skeletonize(
+	labels:npt.NDArray[np.integer],
+	binary_image:bool = False,
+	in_place:bool = False
+) -> npt.NDArray[np.integer]:
+	"""
+	Apply Palagyi's 3D voxel thinning algorithm to `labels`, a binary image.
+
+	Reference:
+
+	K. Palágyi, "A Sequential 3D Curve-Thinning Algorithm Based on Isthmuses,"
+	in Advances in Visual Computing, vol. 8888,
+	G. Bebis, R. Boyle, B. Parvin, D. Koracin, R. McMahan, J. Jerald, 
+	H. Zhang, S. M. Drucker, C. Kambhamettu, M. El Choubassi, Z. Deng, 
+	and M. Carlson, Eds., 
+	Cham: Springer International Publishing, 2014, pp. 406–415.
+	doi: 10.1007/978-3-319-14364-4_39.
+	"""
+	if labels.ndim != 3:
+		raise ValueError(f"This function only supports 3D images. Got: {labels.shape}")
+
+	if labels.size <= 1:
+		return labels
+
+	if in_place and not labels.flags.f_contiguous:
+		raise ValueError("Cannot perform an in-place operation on non-Fortran ordered data.")
+	elif not in_place:
+		labels = np.copy(labels, order="F")
+
+	orig_dtype = labels.dtype
+	if labels.dtype == bool:
+		binary_image = True
+		labels = labels.view(np.uint8)
+
+	if binary_image:
+		fastgaara.thin_palagyi_binary(labels)
+	else:
+		fastgaara.thin_palagyi_multilabel(labels)
+
+	return labels.view(orig_dtype)
+
+

gaara-0.1.0/gaara/fastgaara.cpp

@@ -0,0 +1,72 @@
+#define PYBIND11_DETAILED_ERROR_MESSAGES
+
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+#include <pybind11/stl.h>
+
+#include <cstdlib>
+#include <cmath>
+
+#include "gaara_binary.hpp"
+#include "gaara_multilabel.hpp"
+
+namespace py = pybind11;
+
+template <typename Func>
+void dispatch_skeletonize(const py::array& labels, Func&& func) {
+	py::dtype dt = labels.dtype();
+	const int width = dt.itemsize();
+
+	const uint64_t sx = labels.shape()[0];
+	const uint64_t sy = labels.shape()[1];
+	const uint64_t sz = labels.ndim() > 2 
+		? labels.shape()[2] 
+		: 1;
+
+	void* data = const_cast<void*>(labels.data());
+
+	if (width == 1) {
+		func(static_cast<uint8_t*>(data), sx, sy, sz);
+	}
+	else if (width == 2) {
+		func(static_cast<uint16_t*>(data), sx, sy, sz);
+	}
+	else if (width == 4) {
+		func(static_cast<uint32_t*>(data), sx, sy, sz);
+	}
+	else {
+		func(static_cast<uint64_t*>(data), sx, sy, sz);
+	}
+}
+
+// assumes fortran order
+py::array thin_palagyi_binary(const py::array& labels) {
+	dispatch_skeletonize(labels, [](auto *data, uint64_t sx, uint64_t sy, uint64_t sz) {
+		using T = std::remove_pointer_t<decltype(data)>;
+		return gaara::binary::skeletonize<T>(
+			data,
+			sx, sy, sz
+		);
+	});
+
+	return labels;
+}
+
+// assumes fortran order
+py::array thin_palagyi_multilabel(const py::array& labels) {
+	dispatch_skeletonize(labels, [](auto *data, uint64_t sx, uint64_t sy, uint64_t sz) {
+		using T = std::remove_pointer_t<decltype(data)>;
+		return gaara::multilabel::skeletonize<T>(
+			data,
+			sx, sy, sz
+		);
+	});
+
+	return labels;
+}
+
+PYBIND11_MODULE(fastgaara, m) {
+	m.doc() = "Python interface for Gaara C++ functions."; 
+	m.def("thin_palagyi_binary", &thin_palagyi_binary, "Perform morphological thinning using the Palagyi algorithm on a binary 3D image.");
+	m.def("thin_palagyi_multilabel", &thin_palagyi_multilabel, "Perform morphological thinning using the Palagyi algorithm on a binary 3D image.");
+}

gaara-0.1.0/libcrackle/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022-2026 William Silversmith
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

gaara-0.1.0/libcrackle/builtins.hpp

@@ -0,0 +1,50 @@
+#ifndef _CRACKLE_BUILTINS_HXX_
+#define _CRACKLE_BUILTINS_HXX_
+
+
+#ifdef _MSC_VER
+#  include <intrin.h>
+#  define popcount __popcnt
+
+// https://stackoverflow.com/questions/355967/how-to-use-msvc-intrinsics-to-get-the-equivalent-of-this-gcc-code
+unsigned long ctz(unsigned long value) {
+    unsigned long trailing_zero = 0;
+    if (_BitScanForward(&trailing_zero, value)) {
+        return trailing_zero;
+    }
+    else {
+        return 32;
+    }
+}
+#else
+#  define popcount __builtin_popcount
+#  define ctz __builtin_ctz
+#endif
+
+uint32_t ffs (uint32_t x) {
+#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
+   return __builtin_ffs(x);
+#elif defined _MSC_VER
+  /* _BitScanForward
+     <https://docs.microsoft.com/en-us/cpp/intrinsics/bitscanforward-bitscanforward64> */
+  unsigned long bit;
+  if (_BitScanForward (&bit, x)) {
+    return bit + 1;
+  }
+  return 0;
+#else 
+  if (x == 0) {
+    return 0;
+  }
+  constexpr uint32_t num_bits = sizeof(x) * 8;
+  for (uint32_t i = 0; i < num_bits; i++) {
+    if ((x >> i) & 0x1) {
+        return i + 1;
+    }
+  }
+  return 0;
+#endif
+}
+
+
+#endif