Rename parameters

[haesleinhuepf]

Hi @StRigaud ,

I'm just elaborating how many parameter names have been renamed between pyclesperanto_prototype and pyclesperanto. It's a very long list. If I wanted to rename a parameter, where would be a good place to do this?

I'm a bit confused, because according to the pyclesperanto CLIc wrapper lists parameter names "src0" and "src1" for add_imagesweighted [here](https://github.com/clEsperanto/pyclesperanto/blob/a2dd16cb3fe9947000a40f6a8432e7d1d6f915b1/src/wrapper/tier1.cpp#L13C5-L15C114). But in the python code, its "input_image0" and "input_image1". Is this mapping "src0" -> "input_image0" done automatically somewhere?

Thanks!

Cheers, Robert

[StRigaud]

If I wanted to rename a parameter, where would be a good place to do this?

In the C++ code and doxygen blocks! then it is propagated to the python and java wrapper. Same for anything that touch generated code.

its "input_image0" and "input_image1". Is this mapping "src0" -> "input_image0" done automatically somewhere?

In the C++ i am always using src and dst but for python you where using input_image or output_image (and sometime other names) hence, for these particular parameters I automatically replace src by input_image and dst by output_image in the gencle when generating the python code which call the wrapper code. The wrapper code stick to the C++ names.

[haesleinhuepf]

What if we needed to implement some function-specific naming? E.g. the function generate_distance_matrix consumes to coordinate lists, but these parameters are now called "input_image0" and "input_image1", which might be confusing. Where would I specify better names for these parameters?

[StRigaud]

Quickly, no better options than doing a dirty function only in the python side (interoperability.py)

On the long run, re-work the autogenerated logic and c++ code. Which I am ok to do but after finalizing the Java/paper/etc.

Input and outputs are specifically handled, so difficult to change.

[haesleinhuepf]

Ok, I'm adding here a list of parameters that I think are inappropriate or not reasonable. The notebook which generated this list is here.

Example: The old names (right, _prototype) were self-explanatory, the new names (left) not really:

• [x] Function replace_intensity has diverging parameter names: scalar0 != value_to_replace
• [x] Function replace_intensity has diverging parameter names: scalar1 != value_replacement

My selection:

• Function generate_distance_matrix has diverging parameter names: input_image0 != coordinate_list1
• Function generate_distance_matrix has diverging parameter names: input_image1 != coordinate_list2
• Function generate_distance_matrix has diverging parameter names: output_image != distance_matrix_destination
• Function labelled_spots_to_pointlist has diverging parameter names: output_image != destination_pointlist
• Function masked_voronoi_labeling has diverging parameter names: mask != mask_image
• Function replace_intensities has diverging parameter names: input_image1 != new_values_vector
• Function generate_touch_matrix has diverging parameter names: input_image != label_map
• Function generate_touch_matrix has diverging parameter names: output_image != touch_matrix_destination
• Function multiply_matrix has diverging parameter names: input_image0 != matrix1
• Function multiply_matrix has diverging parameter names: input_image1 != matrix2
• Function multiply_matrix has diverging parameter names: output_image != matrix_destination
• Function onlyzero_overwrite_maximum_diamond has diverging parameter names: output_image0 != flag_dst
• Function onlyzero_overwrite_maximum_diamond has diverging parameter names: output_image1 != destination
• Function nonzero_minimum_box has diverging parameter names: output_image0 != flag_dst
• Function nonzero_minimum_box has diverging parameter names: output_image1 != destination
• Function add_images has diverging parameter names: input_image0 != summand1
• Function add_images has diverging parameter names: input_image1 != summand2
• [x] Function histogram has diverging parameter names: nbins != num_bins
• [x] Function histogram has diverging parameter names: min != minimum_intensity
• [x] Function histogram has diverging parameter names: max != maximum_intensity
• Function copy_horizontal_slice has diverging parameter names: slice != slice_index
• Function exclude_labels_on_edges has diverging parameter names: input_image != label_map_input
• Function exclude_labels_on_edges has diverging parameter names: output_image != label_map_destination
• Function onlyzero_overwrite_maximum_box has diverging parameter names: output_image0 != flag_dst
• Function onlyzero_overwrite_maximum_box has diverging parameter names: output_image1 != destination
• Function label has diverging parameter names: input_image != binary_input
• Function label has diverging parameter names: output_image != labeling_destination
• Function exclude_labels has diverging parameter names: input_image != binary_flaglist
• Function exclude_labels has diverging parameter names: output_image != label_map_destination
• Function extension_ratio_map has diverging parameter names: input_image != labels
• [x] Function paste has diverging parameter names: index_x != destination_x
• [x] Function paste has diverging parameter names: index_y != destination_y
• [x] Function paste has diverging parameter names: index_z != destination_z
• Function erode_labels has diverging parameter names: relabel != relabel_islands
• Function divide_images has diverging parameter names: input_image0 != divident
• Function divide_images has diverging parameter names: input_image1 != divisor
• Function centroids_of_labels has diverging parameter names: input_image != labels
• Function centroids_of_labels has diverging parameter names: output_image != pointlist_destination
• [x] Function centroids_of_labels has diverging parameter names: withBG != include_background
• Function mask_label has diverging parameter names: input_image0 != source
• Function mask_label has diverging parameter names: input_image1 != label_map
• Function generate_binary_overlap_matrix has diverging parameter names: output_image != binary_overlap_matrix_destination
• Function scale has diverging parameter names: interpolate != linear_interpolation
• Function scale has diverging parameter names: resize != auto_size
• Function spots_to_pointlist has diverging parameter names: output_image != destination_pointlist
• Function translate has diverging parameter names: interpolate != linear_interpolation
• Function execute has diverging number of parameters: 6 9 ['anchor', 'kernel_source', 'kernel_name', 'global_size', 'parameters', 'constants'] ['anchor', 'opencl_kernel_filename', 'kernel_name', 'global_size', 'parameters', 'prog', 'constants', 'image_size_independent_kernel_compilation', 'device']
• Function execute has diverging parameter names: constants != prog
• Function smaller_or_equal_constant has diverging parameter names: scalar != constant
• Function count_touching_neighbors has diverging parameter names: input_image != touch_matrix
• Function count_touching_neighbors has diverging parameter names: output_image != touching_neighbors_count_destination
• Function rotate has diverging parameter names: angle_x != angle_around_x_in_degrees
• Function rotate has diverging parameter names: angle_y != angle_around_y_in_degrees
• Function rotate has diverging parameter names: angle_z != angle_around_z_in_degrees
• Function rotate has diverging parameter names: centered != rotate_around_center
• Function rotate has diverging parameter names: interpolate != linear_interpolation
• Function rotate has diverging parameter names: resize != auto_size
• Function flag_existing_labels has diverging parameter names: input_image != label_src
• Function flag_existing_labels has diverging parameter names: output_image != flag_vector_destination
• Function convolve has diverging parameter names: input_image1 != convolution_kernel
• Function nonzero_minimum_diamond has diverging parameter names: output_image0 != flag_dst
• Function nonzero_minimum_diamond has diverging parameter names: output_image1 != destination
• Function power_images has diverging parameter names: input_image0 != source
• Function power_images has diverging parameter names: input_image1 != exponent
• Function affine_transform has diverging parameter names: transform_matrix != transform
• Function affine_transform has diverging parameter names: interpolate != linear_interpolation
• Function affine_transform has diverging parameter names: resize != auto_size
• Function rigid_transform has diverging parameter names: angle_x != angle_around_x_in_degrees
• Function rigid_transform has diverging parameter names: angle_y != angle_around_y_in_degrees
• Function rigid_transform has diverging parameter names: angle_z != angle_around_z_in_degrees
• Function rigid_transform has diverging parameter names: centered != rotate_around_center
• Function rigid_transform has diverging parameter names: resize != auto_size
• Function extend_labeling_via_voronoi has diverging parameter names: input_image != labeling_source
• Function extend_labeling_via_voronoi has diverging parameter names: output_image != labeling_destination
• Function nonzero_maximum_box has diverging parameter names: output_image0 != flag_dst
• Function nonzero_maximum_box has diverging parameter names: output_image1 != destination
• Function nonzero_maximum_diamond has diverging parameter names: output_image0 != flag_dst
• Function nonzero_maximum_diamond has diverging parameter names: output_image1 != destination
• Function local_cross_correlation has diverging parameter names: input_image1 != kernel
• Function write_values_to_positions has diverging parameter names: input_image != positions_and_values
• Function detect_label_edges has diverging parameter names: input_image != label_source
• Function detect_label_edges has diverging parameter names: output_image != binary_destination

I'm afraid end-users may struggle with these kind of changes, especially as they are so many.

There are also many functions with changes of this kind:

• Function add_images_weighted has diverging parameter names: input_image0 != summand1
• Function add_images_weighted has diverging parameter names: input_image1 != summand2
• [x] Function add_images_weighted has diverging parameter names: factor0 != factor1
• [x] Function add_images_weighted has diverging parameter names: factor1 != factor2

[StRigaud]

To be solved later with re-work of the auto-generator and input/output special case management

Numerical parameter name can be changed in CLIc directly.

[StRigaud]

after auick checkup, I think we can change the input / output parameter name without too much issue. Still need to check. I would, however, try to stick to input_image and output_image as much as possible for consistancy, and wait for after the workshop

[haesleinhuepf]

How about input_coordinates or input_labels or input_binary_image here and there? Or after I2K?

[StRigaud]

I will try to generate the python code to check for issue

• input_coordinates -> ok
• input_labels -> ok
• input_binary_image -> input_binary ?
• input_matrix -> ok

This modification should still be done in the CLIC side. I would start with only the input and deal with output later :)

if you wanna start now you can, I can test if no issue when generating but if some problem raise I will side it for after I2K

[StRigaud]

Ok after a quick check, simply changing the input name seems ok with the auto-generator (It seems I was not too stupid when I code it lol).

If you want to change some name @haesleinhuepf go for it but I still push for some caution: focus on the important changes and not too much (we never know)

[haesleinhuepf]

Ok, I'm going to change the most important image parameter names in a separate PR. You can then test it before merging it. And if you merge it after i2k, that's ok, too.