Weird behaviour of HighlightImage—bug or not?

Question

For background, check my answer under this question.

It is clearly stated in the documentation of HighlightImage that the 2nd argument,roi, (region of interest) can be any form of Graphics primitives. So, in my interpretation, all sorts of things that can be presented in Graphics shall work here.

It seems that in most occasions, this rule works quite well, but check this:

img=Graphics[FilledCurve[{{Line[{Scaled[{0.66, 0.21}], 
  Scaled[{0.83, 0.5}], Scaled[{0.66, 0.78}], Scaled[{0.33, 0.78}],
   Scaled[{0.16, 0.5`}], 
  Scaled[{0.33, 0.21}]}]}, {Line[{Scaled[{0.58, 0.35}], 
  Scaled[{0.66, 0.5`}], Scaled[{0.58, 0.64}], 
  Scaled[{0.41, 0.64}], Scaled[{0.33, 0.5`}], 
  Scaled[{0.41, 0.35}]}]}}]]

HighlightImage[Graphics[{Blue, Disk[]}], img, {"Desaturate", .7}]

I suppose the result image of HighlightImage shall desaturate the part inside and outside the FilledCurve, but in fact, HighlightImage seemingly ignore FilledCurve's filling totally and highlighted only the edge part. Weird. Is this a bug?

---

The second problem is even more serious and wierder.

Maybe we can say HighlightImage will failed to recognize FilledCurve or so, but It can, of course, recognize Disk:

HighlightImage[Graphics[{Blue, Disk[]}], 
 Disk[Scaled@{1/2, 1/2}, Scaled[1/4]], {"Lighten", .7}]

But simply a style change will make it fail: change "Lighten" to "Blur"

HighlightImage[Graphics[{Blue, Disk[]}], 
 Disk[Scaled@{1/2, 1/2}, Scaled[1/4]], {"Blur", 3}]

Even more weird.

---

So, is this a bug or I wrote the code in a wrong way? How can I fix it?

Answer 1

I think the problem is sloppy documentation, rather than an implementation bug. A lot of current documentation is incomplete, misleading, or just plain wrong. Here is another example of bad documentation taken from HighlightImage.

The following wrappers can be used
...
$\qquad$Tooltip[e, label] attach an arbitrary tooltip to the element

But it doesn't tell us what an 'element' is. One might reasonably assume tha a tooltip could be attached to either the 1st or the 2nd argument, but it turns out that only the 2nd (the region-of-interest) can take a tooltip.

I demonstrate this using your filled curve. Note, I also give a work-around for the region-of-interest issue you raise.

roi = 
  Graphics[
    {White,
     FilledCurve[
       {{Line[
          {Scaled[{0.66, 0.21}], Scaled[{0.83, 0.5}], Scaled[{0.66, 0.78}], 
           Scaled[{0.33, 0.78}], Scaled[{0.16, 0.5`}], Scaled[{0.33, 0.21}]}]}, 
        {Line[
          {Scaled[{0.58, 0.35}], Scaled[{0.66, 0.5`}], Scaled[{0.58, 0.64}], 
           Scaled[{0.41, 0.64}], Scaled[{0.33, 0.5`}], Scaled[{0.41, 0.35}]}]}}]];
mask = Image[roi];
HighlightImage[
  Graphics[{Blue, Disk[]}], Tooltip[mask, "region of interest"], {"Desaturate", .7}]

HighlightImage[
  Tooltip[Graphics[{Blue, Disk[]}], "not interesting"], mask, {"Desaturate", .7}]

Update

Wjx's comment below got me thinking about this problem again. What set me off is the statement, "I'm just wondering why it will failed to recognize the 'inside part' of an graphics object." I knew that was wrong because adding a tooltip wrapper clearly shows that recognizing the 'inside part' is not causing the failure. The region-of-interest is being recognized correctly. Try

HighlightImage[Graphics[{Blue, Disk[]}], 
  Tooltip[roi, "region of interest"], {"Desaturate", .7}]

and see for yourself. So I wondered what would happen if I did't specify a 3rd argument, but accepted the default background styling.

HighlightImage[Graphics[{Blue, Disk[]}], Tooltip[roi, "region of interest"]]

Well, this version works as expected. Now that is really weird.

So I recant my theory that Wjx has been misled by sloppy documentation. I now take the stand that there is a bug, but not the bug Wjx suggested. The work-around is still to make a mask of the region-of-interest from the vector graphics.