{"id":9739,"library":"fastremap","title":"fastremap Library","description":"fastremap is a highly optimized C++ library with a Python wrapper for high-performance image and point cloud processing. It provides extremely fast functions for remapping, masking, renumbering, finding unique elements, and in-place transposition of 3D labeled images. The current version is 1.18.0, and it maintains an active release cadence with frequent updates.","status":"active","version":"1.18.0","language":"en","source_language":"en","source_url":"https://github.com/seung-lab/fastremap","tags":["image processing","computer vision","numpy","performance","segmentation"],"install":[{"cmd":"pip install fastremap","lang":"bash","label":"Install fastremap"}],"dependencies":[{"reason":"Required for array manipulation and data structures.","package":"numpy","optional":false},{"reason":"Used for some advanced numerical operations.","package":"scipy","optional":false}],"imports":[{"symbol":"remap","correct":"from fastremap import remap"},{"symbol":"remap_inplace","correct":"from fastremap import remap_inplace"},{"symbol":"renumber","correct":"from fastremap import renumber"},{"symbol":"mask","correct":"from fastremap import mask"}],"quickstart":{"code":"import numpy as np\nimport fastremap\n\n# Example 1: Remap an array using a dictionary\narr1 = np.array([1, 2, 1, 3, 0], dtype=np.uint32)\nmapping = {1: 10, 2: 20, 3: 30}\nremapped_arr = fastremap.remap(arr1, mapping)\nprint(f\"Original array: {arr1}\")\nprint(f\"Remapped array: {remapped_arr}\")\n# Expected: Remapped array: [10 20 10 30  0]\n\n# Example 2: In-place remapping\narr2 = np.array([10, 20, 10, 30, 0], dtype=np.uint32)\nreverse_mapping = {10: 1, 20: 2, 30: 3}\nfastremap.remap_inplace(arr2, reverse_mapping)\nprint(f\"Array after in-place remapping: {arr2}\")\n# Expected: Array after in-place remapping: [1 2 1 3 0]\n\n# Example 3: Renumber contiguous labels\narr3 = np.array([0, 5, 2, 0, 5, 10], dtype=np.uint32)\nnew_array, old_to_new_map = fastremap.renumber(arr3)\nprint(f\"Original array for renumber: {arr3}\")\nprint(f\"Renumbered array: {new_array}\")\nprint(f\"Old to new map: {old_to_new_map}\")\n# Expected: Renumbered array: [0 2 1 0 2 3], Old to new map: {0: 0, 5: 2, 2: 1, 10: 3}","lang":"python","description":"This quickstart demonstrates basic usage of `fastremap` for remapping labels in a NumPy array. It shows both non-in-place (`remap`) and in-place (`remap_inplace`) operations, as well as the `renumber` function for making labels contiguous and obtaining the mapping."},"warnings":[{"fix":"Use `arr.copy()` before passing to an `_inplace` function, or use functions like `fastremap.remap` which return a new array.","message":"Many core functions like `remap_inplace` and `transpose_inplace` modify the input NumPy array directly (in-place). If you intend to preserve the original array, use their non-`_inplace` counterparts or create a copy before calling the in-place function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always unpack the return value like `new_array, old_to_new_map = fastremap.renumber(arr)` to access both components.","message":"The `fastremap.renumber` function returns a tuple containing two items: the new renumbered array and a dictionary mapping old labels to new labels. Forgetting to unpack both can lead to errors or misunderstanding the output.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure input arrays for label processing are explicitly cast to appropriate unsigned integer types (e.g., `arr.astype(np.uint32)`).","message":"Functions expecting labels (e.g., `remap`, `renumber`, `mask`) often perform best or explicitly expect unsigned integer data types (like `np.uint32`). Using other types, especially floating-point, may lead to performance degradation, unexpected behavior, or errors due to casting or unsupported operations in the underlying C++.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Convert the array to C-contiguous form before passing it to fastremap: `arr = np.ascontiguousarray(arr)`.","cause":"The underlying C++ routines in fastremap expect NumPy arrays to be C-contiguous for optimal performance and sometimes correctness. If an array is created or sliced in a way that makes it non-contiguous, this error can occur or performance will suffer.","error":"TypeError: Expected array to be C-contiguous."},{"fix":"Ensure your mapping dictionary is comprehensive for all labels you intend to remap. If some labels should remain unchanged, either include them in the map `label: label` or filter the input array before remapping. For labels that should be mapped to zero, include `label: 0`.","cause":"The mapping dictionary provided to `remap` or `remap_inplace` does not contain an entry for one or more non-zero label values present in the input array.","error":"KeyError: <label_value> when using fastremap.remap or remap_inplace with a dictionary."},{"fix":"Check the function signature for `remap` or `remap_inplace`. `remap` can take a dict, while `remap_lut` (or similar) takes a lookup table (array). Ensure the mapping structure and data types (e.g., keys/values in dictionary or elements in lookup table) match the function's expectations. For integer maps, ensure keys and values are integers.","cause":"Incorrectly passing a dictionary to a function that expects a NumPy array for mapping, or vice-versa, or using an incompatible data type for keys/values in the mapping.","error":"ValueError: Cannot convert object to scalar type or TypeError: Argument 'mapping' has incorrect type (expected numpy.ndarray, got dict)"}]}