fastremap 1.15.1__tar.gz → 1.16.0__tar.gz

{fastremap-1.15.1 → fastremap-1.16.0}/.github/workflows/build_wheel.yml

@@ -6,7 +6,7 @@ on:
     tags:
       - '*'
 env:
-  CIBW_SKIP: cp27-* cp33-* cp34-* cp35-* cp36-* cp37-* pp* *-musllinux* cp312-manylinux_i686
+  CIBW_SKIP: cp27-* cp33-* cp34-* cp35-* cp36-* cp37-* cp38* pp* *-musllinux* cp312-manylinux_i686
 
 jobs:
   build_wheels:
@@ -35,6 +35,10 @@ jobs:
           CIBW_BEFORE_BUILD: pip install numpy setuptools wheel cython 
           CIBW_ARCHS_MACOS: "x86_64 arm64"
 
-      - uses: actions/upload-artifact@v3
+
+      - name: Upload built wheels
+        uses: actions/upload-artifact@v4
         with:
-          path: ./wheelhouse/*.whl
+          name: built-wheels-${{ matrix.os }}-${{ matrix.arch }}
+          path: ./wheelhouse/*.whl
+          if-no-files-found: warn

{fastremap-1.15.1 → fastremap-1.16.0}/.github/workflows/test.yml

@@ -14,8 +14,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-20.04, macos-latest, windows-2019]
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - name: Set up Python ${{ matrix.python-version }}

{fastremap-1.15.1 → fastremap-1.16.0}/ChangeLog

@@ -1,6 +1,31 @@
 CHANGES
 =======
 
+1.16.0
+------
+
+* test: add a more stringent random test
+* fix(unique): unique\_via\_sort returns proper data width
+* fix(unique): axis=0, ndim=2 works for higher data widths
+* fix(unique): edge case for uint64 range
+* fix(unique): handle floating point
+* test: make sure fastremap.unique matches np.unique
+* test: sanity check that axis=0 works
+* perf: accelerate special case of np.unique(x, axis=0) where x.ndim=2
+* feat: add indices
+* feat+test: add widen\_dtype and narrow\_dtype
+* docs: show how to use "indices"
+
+1.15.2
+------
+
+* install: restrict to py39+
+* ci: exclude py38 from build
+* ci: remove py38 as it is EOL
+* ci: update runners
+* test: add python3.13
+* ci: upgrade to upload-artifact v4
+
 1.15.1
 ------
 

fastremap-1.16.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: fastremap
+Version: 1.16.0
+Summary: Remap, mask, renumber, unique, and in-place transposition of 3D labeled images. Point cloud too.
+Home-page: https://github.com/seung-lab/fastremap/
+Author: William Silversmith
+Author-email: ws9@princeton.edu
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9,<4.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: numpy
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+[![PyPI version](https://badge.fury.io/py/fastremap.svg)](https://badge.fury.io/py/fastremap)  
+
+# fastremap
+
+Renumber and relabel Numpy arrays at C++ speed and physically convert rectangular Numpy arrays between C and Fortran order using an in-place transposition.   
+
+```python
+import fastremap
+
+uniq, cts = fastremap.unique(labels, return_counts=True) # may be much faster than np.unique
+
+idxs = fastremap.indices(labels, 1231) # important for huge arrays
+
+labels, remapping = fastremap.renumber(labels, in_place=True) # relabel values from 1 and refit data type
+ptc = fastremap.point_cloud(labels) # dict of coordinates by label
+
+labels = fastremap.refit(labels) # resize the data type of the array to fit extrema
+labels = fastremap.refit(labels, value=-35) # resize the data type to fit the value provided
+
+wider_dtype = fastremap.widen_dtype(np.uint32) # np.uint64
+narrower_dtype = fastremap.narrow_dtype(np.uint32) # np.uint16
+
+# remap all occurances of 1 -> 2
+labels = fastremap.remap(labels, { 1: 2 }, preserve_missing_labels=True, in_place=True)
+
+labels = fastremap.mask(labels, [1,5,13]) # set all occurances of 1,5,13 to 0
+labels = fastremap.mask_except(labels, [1,5,13]) # set all labels except 1,5,13 to 0
+
+mapping = fastremap.component_map([ 1, 2, 3, 4 ], [ 5, 5, 6, 7 ]) # { 1: 5, 2: 5, 3: 6, 4: 7 }
+mapping = fastremap.inverse_component_map([ 1, 2, 1, 3 ], [ 4, 4, 5, 6 ]) # { 1: [ 4, 5 ], 2: [ 4 ], 3: [ 6 ] }
+
+fastremap.transpose(labels) # physically transpose labels in-place
+fastremap.ascontiguousarray(labels) # try to perform a physical in-place transposition to C order
+fastremap.asfortranarray(labels) # try to perform a physical in-place transposition to F order
+
+minval, maxval = fastremap.minmax(labels) # faster version of (np.min(labels), np.max(labels))
+
+# computes number of matching adjacent pixel pairs in an image
+num_pairs = fastremap.pixel_pairs(labels)  
+n_foreground = fastremap.foreground(labels) # number of nonzero voxels
+
+# computes the cutout.tobytes(order) of each chunk and returns
+# the binaries indexed by fortran order in the order specified (C or F)
+# If the input image is F contiguous and F is requested, or C and C order,
+# and the image is larger than a single chunk, this will be significantly
+# faster than iterating and using tobytes.
+binaries = fastremap.tobytes(labels, (64,64,64), order="F")
+```
+
+## All Available Functions 
+- **unique:** Faster implementation of `np.unique`.
+- **renumber:** Relabel array from 1 to N which can often use smaller datatypes.
+- **indices:** Optimized search for matching values.
+- **remap:** Custom relabeling of values in an array from a dictionary.
+- **refit:** Resize the data type of an array to the smallest that can contain the most extreme values in it.
+- **narrow_dtype:** Find the next sized up dtype. e.g. uint16 -> uint32
+- **widen_dtype:** Find the next sized down dtype. e.g. uint16 -> uint8
+- **mask:** Zero out labels in an array specified by a given list.
+- **mask_except**: Zero out all labels except those specified in a given list.
+- **component_map**: Extract an int-to-int dictionary mapping of labels from one image containing component labels to another parent labels.  
+- **inverse_component_map**: Extract an int-to-list-of-ints dictionary mapping from an image containing groups of components to an image containing the components.  
+- **remap_from_array:** Same as remap, but the map is an array where the key is the array index and the value is the value.
+- **remap_from_array_kv:** Same as remap, but the map consists of two equal sized arrays, the first containing keys, the second containing values.
+- **asfortranarray:** Perform an in-place matrix transposition for rectangular arrays if memory is contiguous, standard numpy otherwise.
+- **ascontiguousarray:** Perform an in-place matrix transposition for rectangular arrays if memory is contiguous, standard numpy algorithm otherwise.
+- **minmax:** Compute the min and max of an array in one pass.
+- **pixel_pairs:** Computes the number of adjacent matching memory locations in an image. A quick heuristic for understanding if the image statistics are roughly similar to a connectomics segmentation.
+- **foreground:** Count the number of non-zero voxels rapidly.
+- **point_cloud:** Get the X,Y,Z locations of each foreground voxel grouped by label.
+- **tobytes**: Compute the tobytes of an image divided into a grid and return the resultant binaries indexed by their gridpoint in fortran order with the binary in the order requested (C or F).
+
+## `pip` Installation
+
+```bash
+pip install fastremap
+```
+
+*If not, a C++ compiler is required.*
+
+```bash
+pip install numpy
+pip install fastremap --no-binary :all:
+```
+
+## Manual Installation
+
+*A C++ compiler is required.*
+
+```bash
+sudo apt-get install g++ python3-dev 
+mkvirtualenv -p python3 fastremap
+pip install numpy
+
+# Choose one:
+python setup.py develop  
+python setup.py install 
+```
+
+## The Problem of Remapping
+
+Python loops are slow, so Numpy is often used to perform remapping on large arrays (hundreds of megabytes or gigabytes). In order to efficiently remap an array in Numpy you need a key-value array where the index is the key and the value is the contents of that index. 
+
+```python 
+import numpy as np 
+
+original = np.array([ 1, 3, 5, 5, 10 ])
+remap = np.array([ 0, -5, 0, 6, 0, 0, 2, 0, 0, 0, -100 ])
+# Keys:            0   1  2  3  4  5  6  7  8  9    10
+
+remapped = remap[ original ]
+>>> [ -5, 6, 2, 2, -100 ]
+```
+
+If there are 32 or 64 bit labels in the array, this becomes impractical as the size of the array can grow larger than RAM. Therefore, it would be helpful to be able to perform this mapping using a C speed loop. Numba can be used for this in some circumstances. However, this library provides an alternative.
+
+```python
+import numpy as np
+import fastremap 
+
+mappings = {
+  1: 100,
+  2: 200,
+  -3: 7,
+}
+
+arr = np.array([5, 1, 2, -5, -3, 10, 6])
+# Custom remapping of -3, 5, and 6 leaving the rest alone
+arr = fastremap.remap(arr, mappings, preserve_missing_labels=True) 
+# result: [ 5, 100, 200, -5, 7, 10, 6 ]
+```
+
+## The Problem of Renumbering 
+
+Sometimes a 64-bit array contains values that could be represented by an 8-bit array. However, similarly to the remapping problem, Python loops can be too slow to do this. Numpy doesn't provide a convenient way to do it either. Therefore this library provides an alternative solution.
+
+```python
+import fastremap
+import numpy as np
+
+arr = np.array([ 283732875, 439238823, 283732875, 182812404, 0 ], dtype=np.int64) 
+
+arr, remapping = fastremap.renumber(arr, preserve_zero=True) # Returns uint8 array
+>>> arr = [ 1, 2, 1, 3, 0 ]
+>>> remapping = { 0: 0, 283732875: 1, 439238823: 2, 182812404: 3 }
+
+arr, remapping = fastremap.renumber(arr, preserve_zero=False) # Returns uint8 array
+>>> arr = [ 1, 2, 1, 3, 4 ]
+>>> remapping = { 0: 4, 283732875: 1, 439238823: 2, 182812404: 3 }
+
+arr, remapping = fastremap.renumber(arr, preserve_zero=False, in_place=True) # Mutate arr to use less memory
+>>> arr = [ 1, 2, 1, 3, 4 ]
+>>> remapping = { 0: 4, 283732875: 1, 439238823: 2, 182812404: 3 }
+```
+
+## The Problem of In-Place Transposition 
+
+When transitioning between different media, e.g. CPU to GPU, CPU to Network, CPU to disk, it's often necessary to physically transpose multi-dimensional arrays to reformat as C or Fortran order. Tranposing matrices is also a common action in linear algebra, but often you can get away with just changing the strides.
+
+An out-of-place transposition is easy to write, and often faster, but it will spike peak memory consumption. This library grants the user the option of performing an in-place transposition which trades CPU time for peak memory usage. In the special case of square or cubic arrays, the in-place transpisition is both lower memory and faster.
+
+- **fastremap.asfortranarray:** Same as np.asfortranarray but will perform the transposition in-place for 1, 2, 3, and 4D arrays. 2D and 3D square matrices are faster to process than with Numpy.
+- **fastremap.ascontiguousarray:** Same as np.ascontiguousarray but will perform the transposition in-place for 1, 2, 3, and 4D arrays. 2D and 3D square matrices are faster to process than with Numpy.
+
+```python
+import fastremap
+import numpy as np 
+
+arr = np.ones((512,512,512), dtype=np.float32)
+arr = fastremap.asfortranarray(x)
+
+arr = np.ones((512,512,512), dtype=np.float32, order='F')
+arr = fastremap.ascontiguousarray(x)
+```
+
+## C++ Usage
+
+The in-place matrix transposition is implemented in ipt.hpp. If you're working in C++, you can also use it directly like so:
+
+```cpp
+#include "ipt.hpp"
+
+int main() {
+
+  int sx = 128;
+  int sy = 124;
+  int sz = 103;
+  int sw = 3;
+
+  auto* arr = ....;
+
+  // All primitive number types supported
+  // The array will be modified in place, 
+  // so these functions are void type.
+  ipt::ipt<int>(arr, sx, sy);            // 2D
+  ipt::ipt<float>(arr, sx, sy, sz);      // 3D
+  ipt::ipt<double>(arr, sx, sy, sz, sw); // 4D
+
+  return 0;
+}
+```
+
+--  
+Made with <3
+

{fastremap-1.15.1 → fastremap-1.16.0}/README.md

@@ -8,12 +8,18 @@ Renumber and relabel Numpy arrays at C++ speed and physically convert rectangula
 import fastremap
 
 uniq, cts = fastremap.unique(labels, return_counts=True) # may be much faster than np.unique
+
+idxs = fastremap.indices(labels, 1231) # important for huge arrays
+
 labels, remapping = fastremap.renumber(labels, in_place=True) # relabel values from 1 and refit data type
 ptc = fastremap.point_cloud(labels) # dict of coordinates by label
 
 labels = fastremap.refit(labels) # resize the data type of the array to fit extrema
 labels = fastremap.refit(labels, value=-35) # resize the data type to fit the value provided
 
+wider_dtype = fastremap.widen_dtype(np.uint32) # np.uint64
+narrower_dtype = fastremap.narrow_dtype(np.uint32) # np.uint16
+
 # remap all occurances of 1 -> 2
 labels = fastremap.remap(labels, { 1: 2 }, preserve_missing_labels=True, in_place=True)
 
@@ -44,8 +50,11 @@ binaries = fastremap.tobytes(labels, (64,64,64), order="F")
 ## All Available Functions 
 - **unique:** Faster implementation of `np.unique`.
 - **renumber:** Relabel array from 1 to N which can often use smaller datatypes.
+- **indices:** Optimized search for matching values.
 - **remap:** Custom relabeling of values in an array from a dictionary.
 - **refit:** Resize the data type of an array to the smallest that can contain the most extreme values in it.
+- **narrow_dtype:** Find the next sized up dtype. e.g. uint16 -> uint32
+- **widen_dtype:** Find the next sized down dtype. e.g. uint16 -> uint8
 - **mask:** Zero out labels in an array specified by a given list.
 - **mask_except**: Zero out all labels except those specified in a given list.
 - **component_map**: Extract an int-to-int dictionary mapping of labels from one image containing component labels to another parent labels.  

{fastremap-1.15.1 → fastremap-1.16.0}/automated_test.py

@@ -397,6 +397,29 @@ def test_minmax():
   assert minval == np.min(volume)
   assert maxval == np.max(volume)
 
+@pytest.mark.parametrize("dtype", DTYPES)
+def test_unique_axis_0(dtype):
+  arr = np.array([
+    [0,1],
+    [0,2],
+    [0,3],
+    [0,2],
+    [1,2],
+    [2,3],
+  ], dtype=dtype)
+
+  res = fastremap.unique(arr, axis=0)
+  ans = np.unique(arr, axis=0)
+
+  assert np.all(res == ans)
+
+def test_unique_axis_0_random():
+  arr = np.random.randint(0,100000, size=[1000000,2], dtype=np.uint32)
+  a1 = fastremap.unique(arr, axis=0)
+  a2 = np.unique(arr, axis=0)
+  assert np.all(a1 == a2)
+
+
 @pytest.mark.parametrize("order", [ "C", "F" ])
 def test_unique(order):
   def reorder(arr):
@@ -610,9 +633,55 @@ def test_tobytes_misaligned(order):
   except ValueError:
     pass
 
-
-
-
-
+def test_narrow_dtype():
+  assert fastremap.narrow_dtype(np.uint64) == np.uint32
+  assert fastremap.narrow_dtype(np.uint32) == np.uint16
+  assert fastremap.narrow_dtype(np.uint16) == np.uint8
+  assert fastremap.narrow_dtype(np.uint8) == np.uint8
+
+  assert fastremap.narrow_dtype(np.int64) == np.int32
+  assert fastremap.narrow_dtype(np.int32) == np.int16
+  assert fastremap.narrow_dtype(np.int16) == np.int8
+  assert fastremap.narrow_dtype(np.int8) == np.int8
+
+  assert fastremap.narrow_dtype(np.uint64, exotics=True) == np.uint32
+  assert fastremap.narrow_dtype(np.uint32, exotics=True) == np.uint16
+  assert fastremap.narrow_dtype(np.uint16, exotics=True) == np.uint8
+  assert fastremap.narrow_dtype(np.uint8, exotics=True) == np.uint8
+
+  assert fastremap.narrow_dtype(np.int64, exotics=True) == np.int32
+  assert fastremap.narrow_dtype(np.int32, exotics=True) == np.int16
+  assert fastremap.narrow_dtype(np.int16, exotics=True) == np.int8
+  assert fastremap.narrow_dtype(np.int8, exotics=True) == np.int8
+
+  assert fastremap.narrow_dtype(np.float64) == np.float32
+  assert fastremap.narrow_dtype(np.float32) == np.float32
+
+  assert fastremap.narrow_dtype(np.float64, exotics=True) == np.float32
+  assert fastremap.narrow_dtype(np.float32, exotics=True) == np.float16
+
+  assert fastremap.narrow_dtype(np.complex128) == np.complex64
+  assert fastremap.narrow_dtype(np.complex64) == np.complex64
+
+def test_widen_dtype():
+  assert fastremap.widen_dtype(np.uint64) == np.uint64
+  assert fastremap.widen_dtype(np.uint32) == np.uint64
+  assert fastremap.widen_dtype(np.uint16) == np.uint32
+  assert fastremap.widen_dtype(np.uint8) == np.uint16
+
+  assert fastremap.widen_dtype(np.int64) == np.int64
+  assert fastremap.widen_dtype(np.int32) == np.int64
+  assert fastremap.widen_dtype(np.int16) == np.int32
+  assert fastremap.widen_dtype(np.int8) == np.int16
+
+  assert fastremap.widen_dtype(np.float64, exotics=True) == np.longdouble
+  assert fastremap.widen_dtype(np.float64) == np.float64
+  assert fastremap.widen_dtype(np.float32) == np.float64
+  assert fastremap.widen_dtype(np.float16) == np.float32
+
+  assert fastremap.widen_dtype(np.complex64) == np.complex64
+  assert fastremap.widen_dtype(np.complex64, exotics=True) == np.complex128
+  assert fastremap.widen_dtype(np.complex128, exotics=True) == np.clongdouble
+  assert fastremap.widen_dtype(np.clongdouble, exotics=True) == np.clongdouble
 
 

fastremap-1.16.0/fastremap.egg-info/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: fastremap
+Version: 1.16.0
+Summary: Remap, mask, renumber, unique, and in-place transposition of 3D labeled images. Point cloud too.
+Home-page: https://github.com/seung-lab/fastremap/
+Author: William Silversmith
+Author-email: ws9@princeton.edu
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9,<4.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: numpy
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+[![PyPI version](https://badge.fury.io/py/fastremap.svg)](https://badge.fury.io/py/fastremap)  
+
+# fastremap
+
+Renumber and relabel Numpy arrays at C++ speed and physically convert rectangular Numpy arrays between C and Fortran order using an in-place transposition.   
+
+```python
+import fastremap
+
+uniq, cts = fastremap.unique(labels, return_counts=True) # may be much faster than np.unique
+
+idxs = fastremap.indices(labels, 1231) # important for huge arrays
+
+labels, remapping = fastremap.renumber(labels, in_place=True) # relabel values from 1 and refit data type
+ptc = fastremap.point_cloud(labels) # dict of coordinates by label
+
+labels = fastremap.refit(labels) # resize the data type of the array to fit extrema
+labels = fastremap.refit(labels, value=-35) # resize the data type to fit the value provided
+
+wider_dtype = fastremap.widen_dtype(np.uint32) # np.uint64
+narrower_dtype = fastremap.narrow_dtype(np.uint32) # np.uint16
+
+# remap all occurances of 1 -> 2
+labels = fastremap.remap(labels, { 1: 2 }, preserve_missing_labels=True, in_place=True)
+
+labels = fastremap.mask(labels, [1,5,13]) # set all occurances of 1,5,13 to 0
+labels = fastremap.mask_except(labels, [1,5,13]) # set all labels except 1,5,13 to 0
+
+mapping = fastremap.component_map([ 1, 2, 3, 4 ], [ 5, 5, 6, 7 ]) # { 1: 5, 2: 5, 3: 6, 4: 7 }
+mapping = fastremap.inverse_component_map([ 1, 2, 1, 3 ], [ 4, 4, 5, 6 ]) # { 1: [ 4, 5 ], 2: [ 4 ], 3: [ 6 ] }
+
+fastremap.transpose(labels) # physically transpose labels in-place
+fastremap.ascontiguousarray(labels) # try to perform a physical in-place transposition to C order
+fastremap.asfortranarray(labels) # try to perform a physical in-place transposition to F order
+
+minval, maxval = fastremap.minmax(labels) # faster version of (np.min(labels), np.max(labels))
+
+# computes number of matching adjacent pixel pairs in an image
+num_pairs = fastremap.pixel_pairs(labels)  
+n_foreground = fastremap.foreground(labels) # number of nonzero voxels
+
+# computes the cutout.tobytes(order) of each chunk and returns
+# the binaries indexed by fortran order in the order specified (C or F)
+# If the input image is F contiguous and F is requested, or C and C order,
+# and the image is larger than a single chunk, this will be significantly
+# faster than iterating and using tobytes.
+binaries = fastremap.tobytes(labels, (64,64,64), order="F")
+```
+
+## All Available Functions 
+- **unique:** Faster implementation of `np.unique`.
+- **renumber:** Relabel array from 1 to N which can often use smaller datatypes.
+- **indices:** Optimized search for matching values.
+- **remap:** Custom relabeling of values in an array from a dictionary.
+- **refit:** Resize the data type of an array to the smallest that can contain the most extreme values in it.
+- **narrow_dtype:** Find the next sized up dtype. e.g. uint16 -> uint32
+- **widen_dtype:** Find the next sized down dtype. e.g. uint16 -> uint8
+- **mask:** Zero out labels in an array specified by a given list.
+- **mask_except**: Zero out all labels except those specified in a given list.
+- **component_map**: Extract an int-to-int dictionary mapping of labels from one image containing component labels to another parent labels.  
+- **inverse_component_map**: Extract an int-to-list-of-ints dictionary mapping from an image containing groups of components to an image containing the components.  
+- **remap_from_array:** Same as remap, but the map is an array where the key is the array index and the value is the value.
+- **remap_from_array_kv:** Same as remap, but the map consists of two equal sized arrays, the first containing keys, the second containing values.
+- **asfortranarray:** Perform an in-place matrix transposition for rectangular arrays if memory is contiguous, standard numpy otherwise.
+- **ascontiguousarray:** Perform an in-place matrix transposition for rectangular arrays if memory is contiguous, standard numpy algorithm otherwise.
+- **minmax:** Compute the min and max of an array in one pass.
+- **pixel_pairs:** Computes the number of adjacent matching memory locations in an image. A quick heuristic for understanding if the image statistics are roughly similar to a connectomics segmentation.
+- **foreground:** Count the number of non-zero voxels rapidly.
+- **point_cloud:** Get the X,Y,Z locations of each foreground voxel grouped by label.
+- **tobytes**: Compute the tobytes of an image divided into a grid and return the resultant binaries indexed by their gridpoint in fortran order with the binary in the order requested (C or F).
+
+## `pip` Installation
+
+```bash
+pip install fastremap
+```
+
+*If not, a C++ compiler is required.*
+
+```bash
+pip install numpy
+pip install fastremap --no-binary :all:
+```
+
+## Manual Installation
+
+*A C++ compiler is required.*
+
+```bash
+sudo apt-get install g++ python3-dev 
+mkvirtualenv -p python3 fastremap
+pip install numpy
+
+# Choose one:
+python setup.py develop  
+python setup.py install 
+```
+
+## The Problem of Remapping
+
+Python loops are slow, so Numpy is often used to perform remapping on large arrays (hundreds of megabytes or gigabytes). In order to efficiently remap an array in Numpy you need a key-value array where the index is the key and the value is the contents of that index. 
+
+```python 
+import numpy as np 
+
+original = np.array([ 1, 3, 5, 5, 10 ])
+remap = np.array([ 0, -5, 0, 6, 0, 0, 2, 0, 0, 0, -100 ])
+# Keys:            0   1  2  3  4  5  6  7  8  9    10
+
+remapped = remap[ original ]
+>>> [ -5, 6, 2, 2, -100 ]
+```
+
+If there are 32 or 64 bit labels in the array, this becomes impractical as the size of the array can grow larger than RAM. Therefore, it would be helpful to be able to perform this mapping using a C speed loop. Numba can be used for this in some circumstances. However, this library provides an alternative.
+
+```python
+import numpy as np
+import fastremap 
+
+mappings = {
+  1: 100,
+  2: 200,
+  -3: 7,
+}
+
+arr = np.array([5, 1, 2, -5, -3, 10, 6])
+# Custom remapping of -3, 5, and 6 leaving the rest alone
+arr = fastremap.remap(arr, mappings, preserve_missing_labels=True) 
+# result: [ 5, 100, 200, -5, 7, 10, 6 ]
+```
+
+## The Problem of Renumbering 
+
+Sometimes a 64-bit array contains values that could be represented by an 8-bit array. However, similarly to the remapping problem, Python loops can be too slow to do this. Numpy doesn't provide a convenient way to do it either. Therefore this library provides an alternative solution.
+
+```python
+import fastremap
+import numpy as np
+
+arr = np.array([ 283732875, 439238823, 283732875, 182812404, 0 ], dtype=np.int64) 
+
+arr, remapping = fastremap.renumber(arr, preserve_zero=True) # Returns uint8 array
+>>> arr = [ 1, 2, 1, 3, 0 ]
+>>> remapping = { 0: 0, 283732875: 1, 439238823: 2, 182812404: 3 }
+
+arr, remapping = fastremap.renumber(arr, preserve_zero=False) # Returns uint8 array
+>>> arr = [ 1, 2, 1, 3, 4 ]
+>>> remapping = { 0: 4, 283732875: 1, 439238823: 2, 182812404: 3 }
+
+arr, remapping = fastremap.renumber(arr, preserve_zero=False, in_place=True) # Mutate arr to use less memory
+>>> arr = [ 1, 2, 1, 3, 4 ]
+>>> remapping = { 0: 4, 283732875: 1, 439238823: 2, 182812404: 3 }
+```
+
+## The Problem of In-Place Transposition 
+
+When transitioning between different media, e.g. CPU to GPU, CPU to Network, CPU to disk, it's often necessary to physically transpose multi-dimensional arrays to reformat as C or Fortran order. Tranposing matrices is also a common action in linear algebra, but often you can get away with just changing the strides.
+
+An out-of-place transposition is easy to write, and often faster, but it will spike peak memory consumption. This library grants the user the option of performing an in-place transposition which trades CPU time for peak memory usage. In the special case of square or cubic arrays, the in-place transpisition is both lower memory and faster.
+
+- **fastremap.asfortranarray:** Same as np.asfortranarray but will perform the transposition in-place for 1, 2, 3, and 4D arrays. 2D and 3D square matrices are faster to process than with Numpy.
+- **fastremap.ascontiguousarray:** Same as np.ascontiguousarray but will perform the transposition in-place for 1, 2, 3, and 4D arrays. 2D and 3D square matrices are faster to process than with Numpy.
+
+```python
+import fastremap
+import numpy as np 
+
+arr = np.ones((512,512,512), dtype=np.float32)
+arr = fastremap.asfortranarray(x)
+
+arr = np.ones((512,512,512), dtype=np.float32, order='F')
+arr = fastremap.ascontiguousarray(x)
+```
+
+## C++ Usage
+
+The in-place matrix transposition is implemented in ipt.hpp. If you're working in C++, you can also use it directly like so:
+
+```cpp
+#include "ipt.hpp"
+
+int main() {
+
+  int sx = 128;
+  int sy = 124;
+  int sz = 103;
+  int sw = 3;
+
+  auto* arr = ....;
+
+  // All primitive number types supported
+  // The array will be modified in place, 
+  // so these functions are void type.
+  ipt::ipt<int>(arr, sx, sy);            // 2D
+  ipt::ipt<float>(arr, sx, sy, sz);      // 3D
+  ipt::ipt<double>(arr, sx, sy, sz, sw); // 4D
+
+  return 0;
+}
+```
+
+--  
+Made with <3
+

fastremap-1.16.0/fastremap.egg-info/pbr.json

@@ -0,0 +1 @@
+{"git_version": "a7c2749", "is_release": true}

{fastremap-1.15.1 → fastremap-1.16.0}/setup.py

@@ -23,7 +23,7 @@ if sys.platform == 'darwin':
 
 setuptools.setup(
   setup_requires=['pbr', 'cython', 'numpy'],
-  python_requires=">=3.8,<4.0",
+  python_requires=">=3.9,<4.0",
   pbr=True,
   ext_modules=[
     setuptools.Extension(