More info needed for Basic Usage example to work

[MrBobot]

The basic usage example has the below code:

img = testimage("cameraman")
alg = Otsu()
img = binarize(img, alg)

If one just copies and pastes the above into a Julia 1.2 REPL it does not work, even after adding in using ImageBinarization. Digging around the docs found mention of a using TestImages, but simply adding that package to Julia has its own issues when trying to use it on a MacOS 10.14.6 with errors about QuartzImageIO etc.. So for the sake of greater adoption and ease of use it would be worth having a nice self contained examples that one can simply cut and paste and have it work.

[johnnychen94]

Thanks for the feedback.

TestImages.jl is a collection of common test images, and the image I/Os are actually handled by another package, FileIO.jl, which again requires QuartzImageIO.jl or ImageMagick.jl. FileIo.jl doesn't make them as "hard" dependencies to make it a small package (otherwise you'll might to install packages you don't want, e.g., CSVFiles.jl).

I guess the description of FileIO.jl is already clear enough pointing out how you might fix this problem?

julia> using TestImages

julia> img = testimage("cameraman")
Errors encountered while loading "/Users/jc/.julia/packages/TestImages/Aoq3X/images/cameraman.tif".
All errors:
   ArgumentError("Package QuartzImageIO not found in current path:\n- Run `import Pkg; Pkg.add(\"QuartzImageIO\")` to install the QuartzImageIO package.\n")
   ArgumentError("Package ImageMagick not found in current path:\n- Run `import Pkg; Pkg.add(\"ImageMagick\")` to install the ImageMagick package.\n")
Fatal error:
ERROR: ArgumentError: Package QuartzImageIO not found in current path:
- Run `import Pkg; Pkg.add("QuartzImageIO")` to install the QuartzImageIO package.

it says as long as you install QuatzImageIO, this error will be fixed.

This package is one of many image algorithm packages. If you try other packages under JuliaImages such as ImageTransformations.jl, you might meet the same issue. So I think this is not an issue of ImageBinarizations.jl but instead of JuliaImages.

Of course, writing a more complete and descriptive demo gallery is already under consideration.

[MrBobot]

Thanks for the reply, perhaps I should have rephrased the issue so you didn't have to go down the path after your first line Thanks for the feedback. ;) The rest of that I worked out how to make work and should of mentioned in the initial comment.

For low barrier of entry having nicely documented first examples will go a long way to adoption, otherwise you might be selling yourself a little short in that department. People may be already using established tools and stumble across your page for instance and just want to see the "hello world" example work.
Simple line or two mentioning how to install, using Pkg; Pkg.add("ImageBinarization") and adding the using keyword explicitly in the example snippet, are two small suggestions that would be useful.

using ImageBinarization, TestImage
img = testimage("cameraman")
alg = Otsu()
img = binarize(img, alg)

After that I had to figure out how to display it, and tried imshow but hit a stumbling block as you found out in Xref , although all worked fine in Jupyter Lab.

Thanks for your consideration

[zygmuntszpak]

@MrBobot Would you mind reading over the "Getting started" section of the latest documentation and let us know if the explanation addresses your request?