Steve on Image ProcessingApril 3rd, 2009Finding the right level of documentationIt's not always easy to find the right level of documentation for a particular function, as I was reminded by this recent sci.image.processing post slamming the doc for imregionalmax and imextendedmax. (Hi, MH!) I think the main issue is this: Which functions should include concept tutorial information in their reference pages? The reference pages for the functions above describe them in terms of precise but very brief definitions. For example, "regional maxima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a lower value." And that's about it; we don't give you any more context or explanation, nor do say anything about why you might want to use such function. For many functions in MATLAB, I imagine that this level of documentation does not cause any problem at all. For an extreme example, consider the sin function. Our documentation tells you that the function returns the "circular sine." There's no further elaboration about what these terms mean, or why you might want to use sin. That's OK; virtually all MATLAB users learned all about the sine function in their trigonometry class back in high school. Now consider imfilter, which performs two-dimensional and multidimensional convolution and correlation. The reference page contains no tutorial information about what filtering or convolution means, although there is a concrete example illustrating the use of imfilter to simulate motion blur. I think this is still probably OK, since we do assume our readers have some degree of familiarity with basic image processing concepts. We've never intended for our documentation to substitute for basic coursework in a particular domain. For the functions imregionalmax and imextendedmax, though, I accept the documentation complaint as legitimate. These operations are not usually taught in a first course on image processing, and so it's reasonable to expect that many users would be encountering them for the first time in the Image Processing Toolbox. Our technical description of the regional maximum makes this concept harder to understand than it needs to be, and the extended maximum really needs diagrams and maybe a couple of examples to make it clear. I plan to post explanations of these two operations here sometime soon. Depending on the feedback I get, I'll then make suggestions to our writer for expanding the reference pages. 10 Responses to “Finding the right level of documentation”Leave a Reply |
|
|||
|
These postings are the author's and don't necessarily represent the opinions of The MathWorks. |
Steve,
Thank you for this very interesting blog entry. The company I work for just released a Toolbox-style package of M-files for simulating (simple) porous media flow. Granted, this is our first release so the package clearly isn’t as polished as it could be were it produced by, say, The MathWorks.
Still, the package does contain a number of fairly advanced features–some of which have never been released in code before. At least to our knowledge. For documentation we chose to use ‘help’-style descriptions of parameters and return values for the individual functions–often accompanied by simple usage examples. However, we deemed this kind of documentation to be too succinct for new users so we included several fully worked examples demonstrating the features in context. By the way: The PUBLISH function is wonderful!
Overall, I think we have found a fair balance between technical description and tutorials–at least for a first release. We’re considering writing more detailed, i.e., DOC-style, documentation for the individual package functions, but this will have to wait until the next release.
Best regards,
Bård Skaflestad
SINTEF ICT, Applied Mathematics
Bård—Thanks for sharing your thoughts. I love PUBLISH, too! And good luck with your product.
I have once again learned something new at a very opportune time from a TMW blog post. I recently implemented 2-d maxima finding using a method I found mentioned in MATLAB FEX submission 14498:
>> A = rand(1000);
>> tic; B = imdilate(A, ones(3)) == A; toc
Elapsed time is 0.346276 seconds.
However, before switching to imregionalmax (after reading this post) I thought I’d compare it with my current method, and this is what I got:
>> tic; C = imregionalmax(A); toc
Elapsed time is 0.410890 seconds.
>> disp(isequal(B, C))
1
Oliver—imregionalmax is implementing a more complex operation than your imdilate solution. Compare the output of the two solutions with this one-dimensional input:
Those middle 4’s are not considered to be a regional maximum. From that location, if you travel to the right, you can continue uphill. The imdilate solution mark those locations as maxima.
Many thanks for the explanation, Steve.
I guess the moral of this story is that while rand will produce a useful test case for many operations, there are some for which it isn’t suitable, i.e. doesn’t cover all scenarios.
Steve,
I came to “imextendedmax” by way of one of your earlier examples. Since you are part of Mathworks, I like to think that you are providing additional reference information.
More, I think that in looking at the functions available and the options available for each of the functions, there is plenty to absorb. One can always benefit of more…
Perhaps a MatLab wiki would be helpful because other people who know can always chip-in.
Just for instance, I went crazy looking for a way to get the location of imellipses that I had drawn. I had too many to create a handler for each … my luck, there was a note somewhere in the site with the info I needed.
Last, I enjoy your blogs (and the links to other sites you provide).
Cheers.
I struggled trying to understand imregionalmax etc. and I too found the documentation unhelpful - and I teach Computer Vision. I got there in the end, but only after searching the web, looking at the code (which really shouldn’t be needed) and a lot of head scratching. So better documentation would be most welcome. The top priority in my view is clear statements of the algorithms, rather than a tutorial introduction, though that would be useful too.
However, I don’t think this represents a general problem. I haven’t had this experience with other IPT functions - there’s either clear documentation, or like dilation for example they implement well-known operations. So I see imregionalmax (and its family) as a particular lapse, which I hope you can fix, rather than as a symptom of a systematic issue.
I agree about PUBLISH!
David—Thanks for your feedback, that’s useful to know. Hey, I taught Computer Vision a couple of times way back in my previous life. The first time I was assigned to teach it, I felt like I spent the whole term learning it about 60 minutes in advance of the class. ;-)
Hi Steve,
This is an excellent series you’re conducting. Referring to your introductory paper and the basic equation for the degraded image in terms of the PSF and noise, I wanted to implement (without using the built-in matlab functions for it) the weiner filtering of any imported blurred image to the workspace. I’m following the steps outlined and the mathematical equations given on pgs 350 and 355 of Prof Raphael Gonzalez’s ‘Digital Image Processing’text; found the fft2 of the image and typed in the function H(u,v)on pg350 into the matlab workspace, tried to multiply them directly (in freq.domain multiplication), kept getting an error message. I suspect there is something wrong in terms of mismatched data-type. Could you explain to me what i should do to simply get from a simple mathematical expression for the Fourier transform of H(u,v)to a data type that can be multipled with the image fft, to give the degraded image G(u,v)? My aim ultimately is to obtain a coded representation for the expression on pg355, so that i can input any blurred, noisy image to get an acceptable original.
Dave—What error message are you getting? You might try looking at the book Digital Image Processing Using MATLAB. Also, if you have the Image Processing Toolbox you can look at the code for deconvwnr.