fastremap 1.15.1__cp312-cp312-macosx_10_13_x86_64.whl

fastremap-1.15.1.dist-info/AUTHORS

@@ -0,0 +1 @@
+William Silversmith <william.silversmith@gmail.com>

fastremap-1.15.1.dist-info/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

fastremap-1.15.1.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.1
+Name: fastremap
+Version: 1.15.1
+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.8,<4.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: numpy
+
+[![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
+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
+
+# 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.
+- **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.
+- **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.dist-info/RECORD

@@ -0,0 +1,8 @@
+fastremap.cpython-312-darwin.so,sha256=eFRvJhni50GZj6bfXJqEnnljoCz4sml-XAnfHx012-Y,2549152
+fastremap-1.15.1.dist-info/RECORD,,
+fastremap-1.15.1.dist-info/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+fastremap-1.15.1.dist-info/AUTHORS,sha256=Aa4H7O3dtmfq0lF_eATudy11i8K6QAI8LykzASr9bL0,52
+fastremap-1.15.1.dist-info/WHEEL,sha256=kD-LhIT6lUKGukNhSkqq4OnwDJg6bUoeCVUytlUwUF8,111
+fastremap-1.15.1.dist-info/pbr.json,sha256=b77m2uoyXaN-c7-BVxEmFd75JW-Qj02KkOHiAhpnJgk,47
+fastremap-1.15.1.dist-info/top_level.txt,sha256=D-q4-YJbbk7QpuU8fxH9rFQEjV_W6wpdruzTTDV4N5s,10
+fastremap-1.15.1.dist-info/METADATA,sha256=MyHdMXk6pj0pVjRWd0wRmNIMqjJ0TfWP6s4gHE5be40,9561

fastremap-1.15.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: false
+Tag: cp312-cp312-macosx_10_13_x86_64
+

fastremap-1.15.1.dist-info/pbr.json

@@ -0,0 +1 @@
+{"git_version": "0ea7a0b", "is_release": false}

fastremap-1.15.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastremap