Cris’ Image Analysis Blog

Today we released DIPlib version 3.5.2. This release has quite a lot of changes, see the change log. In my last blog post I discussed the graph cut algorithm. This is the largest addition (effort wise) in this release, together with the changes to the dip::Graph class and the new (but similar) dip::DirectedGraph class.

The other major change is in documentation, both for DIPimage (the MATLAB toolbox) and for PyDIP (the Python bindings).

In DIPimage, all the references to DIPlib functions are now links to the on-line documentation:

>> help gaussf
 gaussf   Gaussian filter

  SYNOPSIS:
   image_out = gaussf(image_in,sigma,method,boundary_condition,truncation)

  PARAMETERS:
   sigma: Gaussian parameter for each dimension
   method: Method used to compute the Gaussian. One of:
     - 'fir':    Finite Impulse Resonse filter (convolution with a kernel).
     - 'iir':    Infinte Impulse Response filter (recursive filtering).
     - 'ft':     Convolution via a multiplication in the Fourier Domain.
     - 'best':   Chooses the best option above for your kernel.
     - 'kernel': The convolution kernel is returned, rather than the result
                 of the convolution.
   boundary_condition: Defines how the boundary of the image is handled.
                       See HELP BOUNDARY_CONDITION
   truncation: Determines the size of the Gaussian filters.

  DEFAULTS:
   sigma = 1
   metod = 'best'
   bounary_condition = 'mirror'
   truncation = 3

  NOTES:
   See DERIVATIVE for an explanation of the option 'best'.

   If SIGMA==0 for a particular dimension, that dimension is not processed.

  SEE ALSO:
   derivative

  DIPlib:
   This function calls the DIPlib function dip::Derivative (which calls dip::GaussFIR,
   dip::GaussIIR and dip::GaussFT) and dip::CreateGauss.

The text “derivative” is automatically turned into a link by MATLAB, as it’s the name of a function. The last section previoulsy just named “dip::Derivative”, now it’s a link that the user can click on to go to the documentation. (A shout-out to Andre Zeug for this idea.)

In PyDIP, we previously only had the help text automatically generated by Pybind11, the C++ library that we use to create the Python bindings. We have now added the first paragraph from the on-line help to this:

>>> help(dip.Gauss)
Help on built-in function Gauss in module diplib.PyDIP_bin:

Gauss(...) method of builtins.PyCapsule instance
Gauss(*args, **kwargs)
Overloaded function.

    1. Gauss(in: diplib.PyDIP_bin.Image, sigmas: list[float] = [1.0], derivativeOrder: list[int] = [0], method: str = 'best', boundaryCondition: list[str] = [], truncation: float = 3.0) -> diplib.PyDIP_bin.Image

    Convolution with a Gaussian kernel and its derivatives

    2. Gauss(in: diplib.PyDIP_bin.Image, *, out: diplib.PyDIP_bin.Image, sigmas: list[float] = [1.0], derivativeOrder: list[int] = [0], method: str = 'best', boundaryCondition: list[str] = [], truncation: float = 3.0) -> None

    Convolution with a Gaussian kernel and its derivatives

This help shows the input and output arguments to the function, and if there is more than one legal signature (as is the case for most functions in DIPlib) shows each of them. The text “Convolution with a Gaussian kernel and its derivatives” above is new, the rest is the same as it was before.

This automatically generated help text has some issues, it references the module diplib.PyDIP_bin, which is an internal name, rather than diplib, which is the external name of the module, or dip, which is the name under which the user imported it. It also references the “builtins.PyCapsule instance”, which is an internal Pybind11 construct.

This first paragraph of the help (the short description) is sometimes enough to know what a function does, but if you want to know more about the meaning of the input arguments, how to use the function, or exactly what algorithm(s) it implements, then you need to see the full documentation. Putting the full documentation into the Python help string is not doable. The source for the documentation is Markdown, we could parse that and render it as pure text into the Python help string, but for some functions we make heavy use of equations, which we cannot render in pure text.

Instead, we can help the user find the on-line documentation, like we did in DIPimage. We created a new function, dip.Doc, which will open your default web browser on the documentation for any specific function. For example,

dip.Doc(dip.Gauss)

will open this link. If a function has multiple overloads with separate documentation, then it opens the first one it finds, and presents the list of all the matches:

>>> dip.Doc(dip.OtsuThreshold)
Found multiple matches for OtsuThreshold (opening the first one):
  - https://diplib.org/diplib-docs/histograms.html#dip-OtsuThreshold-Histogram-CL
  - https://diplib.org/diplib-docs/segmentation.html#dip-OtsuThreshold-Image-CL-Image-CL-Image-L

dip.Doc("watershed") will open the documentation for dip::Watershed, because the string exactly matches a function name (without regard to case). If the string doesn’t match a function exactly, it will a Google search in the DIPlib documentation. For example, dip.Doc("diffusion") opens this Google search.

I’d love to hear your opinion about these solutions to the lack of documentation in Python, and any ideas you might have to improve it further!