Here we list the changes to DIPimage as compared to version 2.9. DIPimage is built on DIPlib, which was completely rewritten for this release. Consequently, there are many changes to DIPimage as well. It is possible that we missed some changes here, but hopefully this list will help in porting your old code that used DIPimage to the new version.
It is no longer necessary to call
dip_initialise (which doesn’t exist any more). The DIPlib
library no longer requires initialization.
dip_image object has changed completely internally. Pixel data is stored differently:
tensor images have all samples in the same MATLAB array. Complex images are stored as a
single real matrix, with real and complex samples next to each other (this translates
much more nicely to DIPlib, where complex data is stored in that same way).
dip_image_array pseudo-class no longer exists. Both scalar and tensor
images report to be of class
dip_image. If you need to store multiple images in one
object, create a cell array instead.
Additionally, the tensor no longer can hold arbitrary number of dimensions, it is limited to vectors and matrices, as it is in DIPlib. I don’t expect this to impact any user’s code, and I’d be happy to hear if you actually used tensors with more than two dimensions.
We tried keeping how the
dip_image object is used as similar as possible to how it was
in DIPimage 2, so that users need not change their code. Nonetheless, some changes
size method was discouraged, we asked users to use
Those two functions work as before, except that they don’t return 1 for dimensions that
size now always works like
imsize, except that it always returns at least
two values, and will return 1 for non-existing dimensions. This makes it similar to the
size, and plays nice with the
tensorsize is like
but with a more sensical name, since image arrays no longer exist.
end was discouraged as well, as the meaning changed from
end will always work for spatial dimensions, and cannot be used with tensor indexing.
end will work in
() indexing, but not in
Methods that changed behavior for scalar and tensor images (i.e.
max, etc.) now
always operate only along spatial dimensions. To sum over the tensor dimension, convert
it to a spatial dimension using
Likewise, methods such as
cat used to concatenate images in an
consequently concatenated the various tensor elements as separate images. These functions
now all work along spatial dimensions only, leaving the tensor dimension unaffected.
reshape method now takes pixels column-wise instead of row-wise from the input. This
is the natural way of doing it, as it doesn’t require data copy. It also makes the function
consistent with linear indexing (reshaping an image doesn’t change the linear index of the
pixels). We presume there are few (if any) programs that depend on the old behavior. See
this section of the DIPimage User Manual
for more details).
squeeze method now might reorder dimensions, for the same reasoning as the change to
reshape. The new preference
'CheapSqueeze' can be used to revert to the old behavior
if necessary. See
this section of the DIPimage User Manual
for more details).
There are slight changes to how array data types are handled when converting to a
object and when using an array as input to a DIPimage function. Most importantly, the
DIPlib interface translates double-precision scalar arrays to 0D images of a single-precision
type as long as that does not cause overflow or underflow. This typically yields the expected
results. To avoid this behavior, explicitly cast to
dip_image. For example:
img + 1 vs
img + dip_image(1).
outer methods no longer exist, use
eig_largest has been moved to the toolbox directory, and
eig has gained an option to return
only the eigenvector corresponding to the largest or the smallest eigenvalue.
unique are no longer methods of
Related to the tensor image changes above,
imarfun are now in the
subdirectory, and are identical to the new functions
dip_measurement object has changed completely internally. The interface is identical
It is not (yet?) possible to add a feature.
It is no longer possible to convert to/from a
struct. However, it is possible to convert
Fixed a bug:
msr.featureID now returns an array that is transposed w.r.t. previous versions.
This was a bug that we never fixed because of backwards compatibility, we took this
opportunity to fix it. Now we have total consistency: no matter how the measurement data are
extracted or converted, objects are always rows, and features are always columns.
msr.ID now returns object IDs as a column vector (objects are rows).
A new method,
remap, implements what used to be the independent function
msr_remap is in the
The interactive image display window from
dipshow has had some internal changes.
User-visible changes are:
Three new options in the “Mappings” menu for 3D and 4D images, labeled “Slice”, “Max projection” and “Mean projection”. These allow to display max or mean projection instead of the default thin slice.
Removal of the “Orientation testing” (2D), and “Max projection” and “Sum projection” (3D)
options in the “Actions” menu. The two functions that implemented this functionality,
dipprojection, have also been removed.
Color images are converted to the sRGB color space for display, instead of the linear RGB color
space. This replaces the previously used
'Gamma' preference setting, which is no longer
'GammaGrey' setting is also no longer applied.
A new function
viewslice can be used to display any image (including tensor images and
higher-dimensional images) in DIPviewer.
This is an alternative way to examine images, but none of the tools to programmatically
interact with images displayed through
dipshow will work with this viewer.
Configuration settings accessed through
dipgetpref have been changed since
'CheapSqueeze' controls the behavior of the
dip_image/squeeze method. Set it to
to mimic the behavior of DIPimage versions prior to 3.0 (see the
DIPimage User Manual
for more details).
'DisplayFunction' can be set to either
'dipshow' (the default),
'view5d', and determines which of these functions is invoked by default when the
dip_image/display method is invoked (see the
DIPimage User Manual
for more details).
'FtOption' adds one option to the
ift functions, and allows to configure
DIPimage be be compatible with versions prior to 3.0 (see the
DIPimage User Manual
for more details).
'KeepDataType', which changes how the output data type for arithmetic operations is
chosen, has the same intent but does not always make the same choice. For example
the result is different when mixing signed and unsigned integers. (see the
DIPimage User Manual
for details on the current logic).
'GammaGrey' are no longer active, though they haven’t (yet) been removed.
'DerivativeFlavour', because relevant
functions take these parameters as optional input arguments.
'MorphologicalFlavour', as it didn’t seem useful (the associated function
dip_morph_flavour has also been removed).
'ComputationLimit', because image arithmetic is now always performed by DIPlib.
'InconsistentPixelSize', because the DIPlib library
keeps track of pixel sizes and handles these situations in a fixed manner.
'CommandFilePath', because the DIPimage GUI no longer probes functions to
put them in the menus.
'DebugMode', as DIPlib stack traces are shown or not depending on a
'FFTtype', because DIPlib can optionally be compiled to use FFTW for the FFT.
'FastSubscriptedAssignment', introduced recently in DIPimage 2.9, because the
related functionality has not been ported over (yet?).
Many filters now have a boundary condition parameter. In DIPimage 2, one would change
the boundary condition through a global parameter, which no longer exists. If you never
touched the global parameter, nothing should change for you. If you did change this global
parameter in a program, you now need to pass the value to the relevant functions instead.
Many functions have been added to match new functionality in DIPlib, as well as previous functionality that was not accessible from MATLAB. Some old functions have gained additional parameters to expose more functionality; we tried to do so without breaking backwards compatibility.
Some functions have changed in a way that is not backwards compatible, either by having a different interface or different behavior:
erosion_se, etc. are now folded into
erosion, etc. For
functions with an
_se appended to the name, remove the
_se. Alternatively, the
sub-directory contains these names and forwards the calls to the correct functions.
rankmin_closing now have
rank as the second parameter, instead
percentile. This should make them match the literature better, and make them more
smooth is no longer relevant, moved to the
alias directory. Use
derivative has the 2nd and 3rd arguments switched, it makes more
sense having the order first.
mdhistogram has fewer options, but should still be able to produce the same results as
coords input is transposed w.r.t. previous versions,
for consistency: each row is interpreted as a vertex.
ft now does normalization in the more common way (forward transform not normalized,
inverse transform normalized by 1/N), but an option (
'symmetric') allows to change
the normalization to be consistent with DIPimage 2, which used a symmetric normalization
scheme (both forward and backward transforms use 1/N1/2).
shift shift the image in the opposite direction from what it did in
DIPimage 2, where the shift was unintuitive.
resample produces, by default, a floating-point output image also for linear interpolation.
The function now responds to the
'KeepDataType' setting, making it possible to produce
an interpolated result of the same data type as the input image.
affine_trans rotates in the opposite direction it did before, to match the interpretation
of angles in the rest of the toolbox. The function now also accepts an affine transformation
matrix to direct the transformation. The function
transform provided duplicate functionality
and no longer exists.
find_affine_trans no longer exists, as
fmmatch provides a much better
algorithm to do the same.
rotation3d now produces consistent output with the
'9 shears' methods.
label now returns an unsigned integer image (previously it was a signed integer image).
All functions that work on labeled images expect an unsigned integer image as input.
writeim work differently now, in part because DIPlib natively supports
fewer file types now. The
file_info struct output for
readim has changed somewhat. The last
two input parameters to the old
writeim are no longer supported (
to change the compression method, call
writetiff directly; the pixel size is
always given by the image, use
dip_image/pixelsize to set it.
the interfaces to the corresponding DIPlib file reading functions. RGB TIFF and JPEG images
are now set to the
'sRGB' color space, rather than the (linear)
'RGB' color space.
The AVI reading and writing functions
writedisplayavi depended on
outdated MATLAB functionality and have been removed. You can use MATLAB’s video reading and
writing capabilities, converting between standard MATLAB arrays and a
dip_image is trivial.
countneighbours has been renamed to
countneighbors for consistency in spelling.
mae and several similar functions have been collected in a new function
The old functions are still available in the
slice_ex specify dimensions starting at 1 (not at 0 as previously). This
change is for consistency with the rest of the toolbox. These functions now reorder dimensions
in a way consistent with
dip_image/squeeze (removing dimension 1 causes dimension 3 to become
dimension 1), which is more efficient.
slice_op have been made into
dip_image methods, for efficiency.
get_subpixel no longer supports the
spline interpolation method, this string is still
accepted, but selects the
structuretensor3d has been moved to the
structuretensor now works for any
number of dimensions (with special support for 2D and 3D images).
isophote_curvature have been moved to the
alias directory. The function
curvature now takes
'isophote' as options.
orientation4d has been moved to the
alias directory. A new function
orientation generalizes it to arbitrary dimensionality.
granulometry has changed, but it is still possible to call it the old way. However, the parameters
in this old syntax are interpreted to match the new capabilities of this function.
'verbose' options no longer have an effect. Default values have changed a bit.
ht no longer exists. Use
riesz instead. The Riesz transform is the multi-dimensional generalization
of the 1D Hilbert transform. See also the new function
nconv no longer exists, the new function
normconv will compute the normalized convolution with
a Gaussian, as well as estimate first derivatives using a Gaussian normalized convolution.
dt has a new algorithm, which is used by default. It gives exact results and works for any number of
dimensions, and it should be faster than the previous default algorithm. The old default algorithm can
be executed with
gdt has a new algorithm, which is used by default. It approximates Euclidean distances better. The old
default algorithm can be executed with
gdt(...,3). The second output image is no longer produced. A
new, optional argument specifies a mask image to further constrain paths.
testobject has a changed interface, the input argument order has changed and most arguments are now
name-value pairs. Its functionality has been greatly extended.
orientationspace have a different implementation with different capabilities and a different interface.
measurehelp is no longer a separate function. You can now do
measure help or
jacobi moved to the
alias directory, the
eig method has improved to make
split was shadowing an important new function in MATLAB. It has been renamed to
splitim. To minimize issues
with backwards-compatibility there now is a
split method for
dip_image objects, and a
split function in the
New functions not mentioned above:
help <functionname> in MATLAB to learn what these functions provide.
Old functions not (yet) ported:
These functions will be ported as they are needed.
Old functions that will not be ported:
Old functions that used to be in the
alias directory are no longer. We recommend that you correct affected code,
but if you want, you can always create those aliases again (copy the files from an older version of DIPimage).
If you customized the menus in the DIPimage GUI, you will have to update your
file. If you wrote your own functions that integrated in the GUI, you’ll have to do so through
localdipmenus.m now. Preference setting
'CommandFilePath' no longer exists, nor
the associated function
dipaddpath, only functions mentioned in
are added to the menu system. Functions are no longer probed with
their parameter descriptions are given by
getparams no longer exists. It was a nifty idea but incurred a large overhead. Each function now must
do its own input parameter checking, for example through
The low-level interface has been removed. This interface was composed of functions starting with
and directly mapped the DIPlib functions. Removing this interface simplifies the toolbox code,
as the “normal” toolbox functions did a bunch of parameter parsing, and then called the relevant DIPlib function
through this low-level interface. Now, the “normal” toolbox functions directly call the relevant DIPlib function,
which does the parameter parsing. This is a list of old low-level interface functions, with the corresponding function
to replace it with:
percf_adap, but not yet ported
percf_adap_banana, but not yet ported
arcf, but not yet ported
dip_attenuationcorrection→ not available (but exists in DIPlib)
dip_biasedsigma→ not available
dip_binaryanchorskeleton2d→ not available
dip_binaryrandomvariable→ not available, MATLAB has built-in support for random number generation
dip_binaryskeleton3d→ not available, but
bskeletonproduces a 3D skeleton, if not always correct
dip_changebyteorder→ not available
dip_cityblockdistancetopoint→ not available (but exists in DIPlib)
dip_croptobetterfouriersize→ not available, but see the
fastmode of the
dip_distancebetweenpointsets→ not available
dip_dmllibfile→ not available, no longer meaningful
dip_ellipticdistancetopoint→ not available (but exists in DIPlib)
dip_euclideandistancetopoint→ not available (but exists in DIPlib)
dip_exit→ not available, no longer necessary
dip_exponentialfitcorrection→ not available (but exists in DIPlib)
dip_fm→ not available, but
gdtprovides a different implementation of the Fast Marching algorithm
dip_gaussianrandomvariable→ not available, MATLAB has built-in support for random number generation
dip_gaussiansigma→ not available
dip_getboundary→ not available (the boundary condition is now a parameter to functions that use it)
dip_getlibraryinformation→ not available, information is available in the
dip_gettruncation→ not available (the truncation is now a parameter to functions that use it)
dip_hartleytransform→ not available
dip_imarinvlut→ not available
dip_imarlut→ not available
dip_initialise_libs→ not available, no longer necessary
dip_linefit→ not available
dip_morphologicalgradmag→ not available (but exist in DIPlib)
dip_morphologicalrange→ not available (but exist in DIPlib)
dip_morphologicalsmoothing→ not available (but exist in DIPlib)
dip_morphologicalthreshold→ not available (but exist in DIPlib)
dip_multiscalemorphgrad→ not available (but exist in DIPlib)
dip_orientedgauss→ not available, but can be emulated with
dip_pgst3dline→ not available
dip_pgst3dsurface→ not available
dip_poissonrandomvariable→ not available, MATLAB has built-in support for random number generation
dip_pseudoinverse→ not available
dip_radialdistribution→ not available
dip_randomvariable→ not available, MATLAB has built-in support for random number generation
dip_rankcontrastfilter→ not available
dip_rotation_with_bgval→ not available, but can be implemented by first extending the image with the given background value, and then selecting the appropriate boundary condition in
dip_setboundary→ not available (the boundary condition is now a parameter to functions that use it)
dip_settruncation→ not available (the truncation is now a parameter to functions that use it)
dip_sharpen→ not available (but exist in DIPlib), can be implemented with
img - weight*laplace(img)
dip_sigma→ not available
dip_simplegaussfitimage→ not available (but exist in DIPlib)
dip_simulatedattenuation→ not available (but exist in DIPlib)
dip_sortindices→ not available
dip_structureanalysis→ not available (but exist in DIPlib)
dip_systemdoctor→ not available
'fixed'method, or just
dip_tikhonovmiller→ not available
dip_tikhonovregparam→ not available
dip_uniformrandomvariable→ not available, MATLAB has built-in support for random number generation
dip_upperenvelope→ not available
dip_upperskeleton2d→ not available (but exist in DIPlib)
dipio_appendrawdata→ not available
dipio_getimagereadformats→ not available
dipio_getimagewriteformats→ not available
dipio_getlibraryinformation→ not available
dipio_imagefilegetinfo→ not available (
readimreturns file info as as 2nd output arguments)