API pyClesperanto V.S. Prototype

This is a basic exploration of the API differences between pyclesperanto and the prototype. This is a crude comparison based on function name and localisation in the package, but it can quickly help you find possible differences and help you convert from one to an other.

We are trying to minimise the effort require to switch from the prototype to pyclesperanto using aliases and overloading of functions. Some function might be renamed, have their parameters changed, or not be available anymore. This document is here to quickly help you identify big differences between the two.

We value community feedback and communications, if you are facing issue with a function renamed or missing, please reach out to us!

import pyclesperanto as cle
import pyclesperanto_prototype as clep

print(f"pyclesperanto ({cle.__version__}) v.s. pyclespernato_prototype ({clep.__version__})")

pyclesperanto (0.16.0) v.s. pyclespernato_prototype (0.24.4)

modules = ["_core", "_array", "_memory", "_functionalities", "_utils", "_operators", "_interroperability"]
core_cle = {func for module in modules for func in dir(getattr(cle, module, [])) if not func.startswith("_") and not func[0].isupper()}
core_clep = {func for func in dir(getattr(clep, "_tier0", []))  if not func.startswith("_") and not func[0].isupper()}

Core functions

We call core functions, the various operations requiered for the library usage such like memory copy or device selection. Several function have disapeared due to the fact that all heavy GPU functionnality and management are now dealt with in the C++ code of clEsperanto.

both = sorted(core_cle.intersection(core_clep))
new = sorted(core_cle.difference(core_clep))
old = sorted(core_clep.difference(core_cle))

print(f"\033[1mFunctions available in both pyclesperanto and prototype ({len(both)}):\033[0m")
for func in both:
    print(f" - {func}")
print()
print(f"\033[1mFunctions available only in pyclesperanto ({len(new)}):\033[0m")
for func in new:
    print(f" - {func}")
print()
print(f"\033[1mFunctions available only in prototype ({len(old)}):\033[0m")
for func in old:
    print(f" - {func}")

Functions available in both pyclesperanto and prototype (14):
 - asarray
 - available_device_names
 - cl_info
 - create
 - create_like
 - execute
 - get_device
 - operation
 - operations
 - pull
 - push
 - search_operation_names
 - select_device
 - set_wait_for_kernel_finish

Functions available only in pyclesperanto (26):
 - affine_transform
 - cl_buffer_datatype_dict
 - default_initialisation
 - empty
 - empty_like
 - from_array
 - get
 - getmembers
 - imshow
 - info
 - is_image
 - isfunction
 - label
 - list_available_backends
 - list_available_devices
 - native_execute
 - np
 - path
 - reshape
 - select_backend
 - set
 - to_device
 - wait_for_kernel_to_finish
 - warnings
 - zeros
 - zeros_like

Functions available only in prototype (30):
 - categories
 - create_2d_xy
 - create_2d_xz
 - create_2d_yx
 - create_2d_yz
 - create_2d_zx
 - create_2d_zy
 - create_binary_like
 - create_from_pointlist
 - create_image
 - create_labels_like
 - create_matrix_from_pointlists
 - create_none
 - create_pointlist_from_labelmap
 - create_square_matrix_from_labelmap
 - create_square_matrix_from_pointlist
 - create_square_matrix_from_two_labelmaps
 - create_vector_from_labelmap
 - create_vector_from_square_matrix
 - create_zyx
 - empty_image
 - empty_image_like
 - nparray
 - platform
 - plugin_function
 - pull_zyx
 - push_zyx
 - radius_to_kernel_size
 - set_device_scoring_key
 - sigma_to_kernel_size

Tiers functions

def compare_tiers(module1, module2, module1_name, module2_name):
    tiers = ["_tier1", "_tier2", "_tier3", "_tier4", "_tier5", "_tier6", "_tier7", "_tier8", "_tier9"]
    module1_tier_funcs = {func for module in tiers for func in dir(getattr(module1, module, [])) if not func.startswith("_") and not func[0].isupper()}
    module2_tier_funcs = {func for module in tiers for func in dir(getattr(module2, module, [])) if not func.startswith("_") and not func[0].isupper()}

    shared_in_both = module1_tier_funcs.intersection(module2_tier_funcs)
    missing_in_module1 = module2_tier_funcs.difference(module1_tier_funcs)
    missing_in_module2 = module1_tier_funcs.difference(module2_tier_funcs)

    print(f"\033[1m- Functions in both {module2_name} and {module1_name} ({len(shared_in_both)}):\033[0m")
    for func in sorted(shared_in_both):
        print(f" - {func}")
    print()
    print(f"\033[1m- Functions in {module1_name} not in {module2_name} ({len(missing_in_module2)}):\033[0m")
    for func in sorted(missing_in_module2):
        print(f" - {func}")
    print()
    print(f"\033[1m- Functions in {module2_name} not in {module1_name} ({len(missing_in_module1)}):\033[0m")
    for func in sorted(missing_in_module1):
        print(f" - {func}")

compare_tiers(cle, clep, "pyclesperanto", "prototype")

- Functions in both prototype and pyclesperanto (218):
 - absolute
 - absolute_difference
 - add_image_and_scalar
 - add_images
 - add_images_weighted
 - affine_transform
 - append
 - array_equal
 - binary_and
 - binary_edge_detection
 - binary_not
 - binary_or
 - binary_subtract
 - binary_xor
 - block_enumerate
 - bottom_hat_box
 - bottom_hat_sphere
 - bounding_box
 - center_of_mass
 - centroids_of_labels
 - clear
 - clip
 - closing_box
 - closing_labels
 - closing_sphere
 - combine_labels
 - convolve
 - copy
 - copy_horizontal_slice
 - copy_slice
 - copy_vertical_slice
 - count
 - count_touching_neighbors
 - crop
 - crop_border
 - cubic_root
 - degrees_to_radians
 - detect_label_edges
 - detect_maxima_box
 - detect_minima_box
 - difference_of_gaussian
 - dilate_box
 - dilate_labels
 - dilate_sphere
 - divide_by_gaussian_background
 - divide_images
 - divide_scalar_by_image
 - equal
 - equal_constant
 - erode_box
 - erode_connected_labels
 - erode_labels
 - erode_sphere
 - eroded_otsu_labeling
 - exclude_labels
 - exclude_labels_on_edges
 - exclude_labels_outside_size_range
 - exclude_labels_with_map_values_out_of_range
 - exclude_labels_with_map_values_within_range
 - exclude_large_labels
 - exclude_small_labels
 - exponential
 - extend
 - extend_labeling_via_voronoi
 - extension_ratio_map
 - flag_existing_labels
 - flip
 - gamma_correction
 - gauss_otsu_labeling
 - gaussian_blur
 - generate_binary_overlap_matrix
 - generate_distance_matrix
 - generate_touch_matrix
 - gradient_x
 - gradient_y
 - gradient_z
 - greater
 - greater_constant
 - greater_or_equal
 - greater_or_equal_constant
 - hessian_eigenvalues
 - histogram
 - index
 - insert
 - invert
 - jaccard_index
 - label_pixel_count_map
 - label_spots
 - labelled_spots_to_pointlist
 - laplace_box
 - laplace_diamond
 - large_hessian_eigenvalue
 - local_cross_correlation
 - logarithm
 - mask
 - mask_label
 - masked_voronoi_labeling
 - maximum_box
 - maximum_image_and_scalar
 - maximum_images
 - maximum_of_all_pixels
 - maximum_position
 - maximum_sphere
 - maximum_x_projection
 - maximum_y_projection
 - maximum_z_projection
 - mean_box
 - mean_intensity_map
 - mean_of_all_pixels
 - mean_sphere
 - mean_squared_error
 - mean_x_projection
 - mean_y_projection
 - mean_z_projection
 - median_box
 - median_sphere
 - minimum_box
 - minimum_image_and_scalar
 - minimum_images
 - minimum_of_all_pixels
 - minimum_of_masked_pixels
 - minimum_position
 - minimum_sphere
 - minimum_x_projection
 - minimum_y_projection
 - minimum_z_projection
 - mode_box
 - mode_sphere
 - modulo_images
 - multiply_image_and_scalar
 - multiply_images
 - multiply_matrix
 - nan_to_num
 - nonzero_maximum_box
 - nonzero_maximum_diamond
 - nonzero_minimum_box
 - nonzero_minimum_diamond
 - not_equal
 - not_equal_constant
 - onlyzero_overwrite_maximum_box
 - onlyzero_overwrite_maximum_diamond
 - opening_box
 - opening_labels
 - opening_sphere
 - paste
 - pixel_count_map
 - pop
 - power
 - power_images
 - radians_to_degrees
 - range
 - reciprocal
 - reduce_stack
 - relabel_sequential
 - remove
 - replace_intensities
 - replace_intensity
 - reverse
 - rigid_transform
 - rotate
 - scale
 - set
 - set_column
 - set_image_borders
 - set_nonzero_pixels_to_pixelindex
 - set_plane
 - set_ramp_x
 - set_ramp_y
 - set_ramp_z
 - set_row
 - set_where_x_equals_y
 - set_where_x_greater_than_y
 - set_where_x_smaller_than_y
 - sign
 - small_hessian_eigenvalue
 - smaller
 - smaller_constant
 - smaller_or_equal
 - smaller_or_equal_constant
 - smooth_labels
 - sobel
 - sort
 - spots_to_pointlist
 - square
 - square_root
 - squared_difference
 - standard_deviation_box
 - standard_deviation_sphere
 - statistics_of_background_and_labelled_pixels
 - statistics_of_labelled_pixels
 - sub_stack
 - subtract_gaussian_background
 - subtract_image_from_scalar
 - subtract_images
 - sum_of_all_pixels
 - sum_reduction_x
 - sum_x_projection
 - sum_y_projection
 - sum_z_projection
 - threshold_otsu
 - top_hat_box
 - top_hat_sphere
 - translate
 - transpose_xy
 - transpose_xz
 - transpose_yz
 - undefined_to_zero
 - variance_box
 - variance_sphere
 - voronoi_labeling
 - voronoi_otsu_labeling
 - write_values_to_positions
 - x_position_of_maximum_x_projection
 - x_position_of_minimum_x_projection
 - y_position_of_maximum_y_projection
 - y_position_of_minimum_y_projection
 - z_position_of_maximum_z_projection
 - z_position_of_minimum_z_projection

- Functions in pyclesperanto not in prototype (56):
 - binary_closing
 - binary_dilate
 - binary_erode
 - binary_infsup
 - binary_opening
 - binary_supinf
 - bottom_hat
 - clic
 - closing
 - concatenate_along_x
 - concatenate_along_y
 - concatenate_along_z
 - connected_component_labeling
 - connected_components_labeling
 - detect_maxima
 - detect_minima
 - dilation
 - erosion
 - filter_label_by_size
 - grayscale_closing
 - grayscale_dilate
 - grayscale_erode
 - grayscale_opening
 - importlib
 - label_bounding_box
 - laplace
 - maximum_filter
 - mean_filter
 - median
 - minimum_filter
 - mode
 - morphological_chan_vese
 - multiply_image_and_position
 - nonzero_maximum
 - nonzero_minimum
 - np
 - onlyzero_overwrite_maximum
 - opening
 - plugin_function
 - read_values_from_positions
 - reduce_labels_to_centroids
 - reduce_labels_to_label_edges
 - remove_labels
 - remove_labels_on_edges
 - remove_labels_with_map_values_out_of_range
 - remove_labels_with_map_values_within_range
 - remove_large_labels
 - remove_small_labels
 - replace_value
 - replace_values
 - smooth_connected_labels
 - standard_deviation
 - std_z_projection
 - top_hat
 - variance_filter
 - warnings

- Functions in prototype not in pyclesperanto (204):
 - apply_vector_field
 - arg_maximum_x_projection
 - arg_maximum_y_projection
 - arg_maximum_z_projection
 - arg_minimum_x_projection
 - arg_minimum_y_projection
 - arg_minimum_z_projection
 - array_equiv
 - artificial_objects_2d
 - artificial_tissue_2d
 - average_distance_of_n_closest_neighbors_map
 - average_distance_of_n_closest_points
 - average_distance_of_n_far_off_distances
 - average_distance_of_n_far_off_points
 - average_distance_of_n_nearest_distances
 - average_distance_of_n_nearest_neighbors_map
 - average_distance_of_n_shortest_distances
 - average_distance_of_touching_neighbors
 - average_distance_to_n_nearest_other_labels_map
 - average_neighbor_distance_map
 - binary_intersection
 - binary_union
 - cbrt
 - centroids_of_background_and_labels
 - close_index_gaps_in_label_map
 - combine_horizontally
 - combine_vertically
 - concatenate_stacks
 - connected_components_labeling_box
 - connected_components_labeling_diamond
 - deskew_x
 - deskew_y
 - dilate_box_slice_by_slice
 - dilate_sphere_slice_by_slice
 - distance_matrix_to_mesh
 - downsample_slice_by_slice_half_median
 - downsample_xy_by_half_median
 - draw_angle_mesh_between_touching_labels
 - draw_box
 - draw_distance_mesh_between_n_nearest_labels
 - draw_distance_mesh_between_proximal_labels
 - draw_distance_mesh_between_touching_labels
 - draw_line
 - draw_mesh_between_labels_with_touch_portion_in_range
 - draw_mesh_between_n_closest_labels
 - draw_mesh_between_n_most_touching_labels
 - draw_mesh_between_proximal_labels
 - draw_mesh_between_touching_labels
 - draw_sphere
 - draw_touch_portion_mesh_between_touching_labels
 - draw_touch_portion_ratio_mesh_between_touching_labels
 - erode_box_slice_by_slice
 - erode_sphere_slice_by_slice
 - euclidean_distance_from_label_centroid_map
 - exclude_labels_out_of_size_range
 - exclude_labels_with_average_values_out_of_range
 - exclude_labels_with_average_values_within_range
 - exclude_labels_with_map_values_equal_to_constant
 - exclude_labels_with_map_values_not_equal_to_constant
 - exclude_labels_with_values_equal_to_constant
 - exclude_labels_with_values_not_equal_to_constant
 - exclude_labels_with_values_out_of_range
 - exclude_labels_with_values_within_range
 - execute_separable_kernel
 - exp
 - extend_labels_with_maximum_radius
 - extended_depth_of_focus_variance_projection
 - fabs
 - fill_diagonal
 - fill_zeros_inpainting
 - flag_existing_intensities
 - generate_angle_matrix
 - generate_distal_neighbors_matrix
 - generate_maximum_intensity_between_points_matrix
 - generate_mean_intensity_between_points_matrix
 - generate_minimum_intensity_between_points_matrix
 - generate_n_most_touching_neighbors_matrix
 - generate_n_nearest_neighbors_matrix
 - generate_proximal_neighbors_matrix
 - generate_should_touch_matrix
 - generate_standard_deviation_intensity_between_points_matrix
 - generate_touch_count_matrix
 - generate_touch_mean_intensity_matrix
 - generate_touch_mean_intensity_within_range_matrix
 - generate_touch_portion_matrix
 - generate_touch_portion_within_range_neighbors_matrix
 - imread
 - imshow
 - is_matrix_symmetric
 - label
 - label_centroids_to_pointlist
 - label_maximum_extension_map
 - label_maximum_extension_ratio_map
 - label_maximum_intensity_map
 - label_mean_extension_map
 - label_mean_intensity_map
 - label_minimum_intensity_map
 - label_nonzero_pixel_count_map
 - label_nonzero_pixel_count_ratio_map
 - label_overlap_count_map
 - label_standard_deviation_intensity_map
 - label_to_mask
 - local_maximum_touching_neighbor_count_map
 - local_mean_touching_neighbor_count_map
 - local_median_touching_neighbor_count_map
 - local_minimum_touching_neighbor_count_map
 - local_standard_deviation_touching_neighbor_count_map
 - log
 - logical_and
 - logical_not
 - logical_or
 - logical_xor
 - map_array
 - maximum
 - maximum_distance_of_n_closest_points
 - maximum_distance_of_n_shortest_distances
 - maximum_distance_of_touching_neighbors
 - maximum_extension_map
 - maximum_intensity_map
 - maximum_of_distal_neighbors_map
 - maximum_of_n_most_touching_neighbors_map
 - maximum_of_n_nearest_neighbors_map
 - maximum_of_proximal_neighbors_map
 - maximum_of_touch_portion_within_range_neighbors_map
 - maximum_of_touching_neighbors
 - maximum_of_touching_neighbors_map
 - mean_extension_map
 - mean_of_distal_neighbors_map
 - mean_of_n_most_touching_neighbors_map
 - mean_of_n_nearest_neighbors_map
 - mean_of_proximal_neighbors_map
 - mean_of_touch_portion_within_range_neighbors_map
 - mean_of_touching_neighbors
 - mean_of_touching_neighbors_map
 - median_of_touching_neighbors
 - merge_annotated_touching_labels
 - merge_labels_according_to_touch_matrix
 - merge_labels_with_border_intensity_within_range
 - merge_touching_labels
 - minimum
 - minimum_distance_of_touching_neighbors
 - minimum_intensity_map
 - minimum_of_distal_neighbors_map
 - minimum_of_n_most_touching_neighbors_map
 - minimum_of_n_nearest_neighbors_map
 - minimum_of_proximal_neighbors_map
 - minimum_of_touch_portion_within_range_neighbors_map
 - minimum_of_touching_neighbors
 - minimum_of_touching_neighbors_map
 - mod
 - mode_of_distal_neighbors_map
 - mode_of_n_most_touching_neighbors_map
 - mode_of_n_nearest_neighbors_map
 - mode_of_proximal_neighbors_map
 - mode_of_touch_portion_within_range_neighbors_map
 - mode_of_touching_neighbors
 - mode_of_touching_neighbors_map
 - multiply_image_and_coordinate
 - n_closest_points
 - neighbors_of_neighbors
 - point_index_list_to_mesh
 - point_index_list_to_touch_matrix
 - pointlist_to_labelled_spots
 - prefix_in_x
 - proximal_neighbor_count
 - proximal_neighbor_count_map
 - proximal_other_labels_count
 - proximal_other_labels_count_map
 - push_regionprops
 - push_regionprops_column
 - read_intensities_from_map
 - read_intensities_from_positions
 - regionprops
 - remainder
 - resample
 - set_non_zero_pixels_to_pixel_index
 - sorensen_dice_coefficient
 - sqrt
 - standard_deviation_intensity_map
 - standard_deviation_of_distal_neighbors_map
 - standard_deviation_of_n_most_touching_neighbors_map
 - standard_deviation_of_n_nearest_neighbors_map
 - standard_deviation_of_proximal_neighbors_map
 - standard_deviation_of_touch_portion_within_range_neighbors_map
 - standard_deviation_of_touching_neighbors
 - standard_deviation_of_touching_neighbors_map
 - standard_deviation_z_projection
 - statistics_of_image
 - statistics_of_labelled_neighbors
 - stitch_horizontally_linear_blending
 - stitch_vertically_linear_blending
 - subtract_labels
 - symmetric_maximum_matrix
 - symmetric_mean_matrix
 - symmetric_minimum_matrix
 - symmetric_sum_matrix
 - threshold
 - touch_matrix_to_adjacency_matrix
 - touch_matrix_to_mesh
 - touch_portion_within_range_neighbor_count
 - touch_portion_within_range_neighbor_count_map
 - touching_neighbor_count_map
 - z_position_projection
 - z_position_range_projection