Documentation for image() is incomplete

[JasonMDavey]

Issue description

The reference page for image() does not document the functionality for drawing a clipped section of the source image. I ended up having to figure out the parameters for this (9-argument) version of image() through trial and error.

URL(s) of affected page(s)

https://processing.org/reference/image_.html

Proposed fix

Add example and documentation for this version.

The actual parameters seem to be: image(image, targetX, targetY, targetWidth, targetHeight, sourceLeft, sourceTop, sourceRight, sourceBottom);

[jeremydouglass]

It isn't clear what you are trying to do when you say "drawing a clipped section of the source", but if you have a PImage img and want to drop it cropped, use img.get():

https://processing.org/reference/PImage_get_.html

If you want to crop something from the canvas, use get():

https://processing.org/reference/get_.html

Just for your information, trial and error isn't necessary -- you can follow the JavaDoc from the top of the page, and image() is listed here:

http://processing.github.io/processing-javadocs/core/processing/core/PApplet.html#image-processing.core.PImage-float-float-float-float-int-int-int-int-

...or look it up in the source on the Processing repo to see the implementation.

[JasonMDavey]

Thanks Jeremy.

I filed this as a documentation bug - not an issue with functionality. I would have expected this signature for image() to have been included in the main reference page for image(). Is there any reason why it shouldn't be included there?

I was vaguely aware that this signature for image() existed, but didn't find it in the reference, I Googled around and also didn't find anything satisfactory. So while it is indeed covered in the JavaDoc (thanks for the link!) I'm not sure that's an ideal solution. The description there is also a rather cursory - e.g. are the UV coordinates in the typical 0-1 range, or based on pixel coordinates? Honestly I'd probably still need to employ a bit of trial and error to be sure about how that would behave.

[jeremydouglass]

Thanks @JasonD43.

Processing is documented at three levels -- in the code itself, in the JavaDoc, and in the reference. The reference is especially oriented towards learners, of all ages, and guides them towards recommended usage. For this reason, it systematically omits complex method signatures that they should not use. Some of the reference entries point explicitly to the JavaDoc, saying "and many more methods not listed here" -- I'm thinking of PGraphics, or ArrayList, for two examples -- but some entries don't even say that, they just have the generic "also see the JavaDoc" at the top of the page.

In this case, there is a 9-argument form of .image(), but using it isn't the recommended way of clipping an image, so it isn't advertised in the reference because it would mislead and confuse far more people than it would help -- I believe that are other, better ways to clip an image with the API unless you have extremely specific needs in an advanced project. Honestly, I don't think I've ever seen that signature used outside a library, and I've read ~20,000 Processing posts on the forums in the past 4-5 years.

edit: I was wrong about that, see: https://discourse.processing.org/search?q=public%20void%20image(PImage%20img%2C%20float%20a%2C%20float%20b%2C%20float%20c%2C%20float%20d%2C%20int%20u1%2C%20int%20v1%2C%20int%20u2%2C%20int%20v2)

So, to improve the reference documentation, you could add a generic statement like "for more ways to use image(), see the reference" -- but it might help to start out by better documenting that method in the source / JavaDoc first. No such thing as too much documentation there!

Or just add the signature to the reference too. I'm not 100% against it, but my first instinct is no (and this is only my personal opinion -- I don't merge commits on this repo). When someone is clicking around the reference trying to crop an image, I wouldn't want them to find it without a warning label on it. Honestly, the 5-argument image() is already a real pain with new users -- they use it in draw and their sketches develop horrible performance problems, and they don't know why. My two cents.

[JasonMDavey]

I see - I didn't know where the reference was supposed to be pitched exactly in terms of level of detail.

I can definitely see the argument for omitting methods inside PGraphics, as it basically duplicates all of the core rendering functions, and so would be fairly redundant. And ArrayList is not even part of the Processing codebase.

Coming from using other rools/frameworks, this method seemed like a very natural way to achieve my goal (I was using this for spritesheet-style animation). So I didn't imagine it would be seen as unusual. Also, somewhat tangentially, this signature is the one which pops up in the editor if you Ctrl+enter autocomplete after starting to type "image".

It does look like a couple of other folks were also tripped up in a similar way (see e.g. https://discourse.processing.org/t/should-negative-width-in-image-produce-mirroring/6366/9 from your search results).

Are there other basic rendering functions which exist in the reference, but have undocumented signatures?

The issue with a note like "also see the Javadocs" for someone like me (who is not familiar with how Processing works internally, or what its preprocessor does) is that I wouldn't even know where to look, as I was not aware of which class defines this method!

[jeremydouglass]

Spritesheets are a great use case. I was actually thinking of quark's Sprites library. I could see that, honestly. It would help if the reference had an illustrative example.

If you want to display a crop but don't want to create an intermediate PImage, I think you can just do this:

image(img.get(x, y, w, h), x2, y2);

or blend() to map two regions and control blendmode at the same time; or copy() to map two regions and resize at the same time.

Of course, those reference pages have nine-argument forms, so if them, why not image() as well, I suppose. It feels redundant, but that isn't the worst thing.

Are there other basic rendering functions which exist in the reference, but have undocumented signatures?

Not undocumented, but ones that listed in the full JavaDoc and not the reference, yes, I think most of them do, if I understand what you mean. Look at PShape, for example, for rendering shapes. It has the same "Some of the methods are listed below, but the full list used for creating and modifying shapes is available here in the Processing Javadoc." PImage, PGraphics... also non-rendering classes, like Table... they all have methods that are documented in the JavaDoc, but not the reference.

[JasonMDavey]

Your example there using img.get() is still creating an intermediate PImage, presumably, even if we don't store it in a variable? It's allocating and copying all of those pixels each time.

Not undocumented, but ones that listed in the full JavaDoc and not the reference, yes, I think most of them do, if I understand what you mean

I mean top-level functions like rect() or ellipse() (I guess technically those are from PApplet, but from the user's point of view they're the fundamental top-level functions). Aren't all of their signatures otherwise included in the reference? I can more easily understand stuff like PShape not being fully documented there.

[jeremydouglass]

Oh, got it. Yes, PApplet methods too. For one example, loadStrings() has two signatures in the reference, but four in the JavaDoc.

https://processing.org/reference/loadStrings_.html http://processing.github.io/processing-javadocs/core/processing/core/PApplet.html#loadStrings-java.io.File-

I haven't checked through systematically, but I'm sure there are many more.

It's allocating and copying all of those pixels each time.

Yes, that is true. By contrast image(9) doesn't copy into an intermediate PImage, it just calls the internal PGraphics.imageImpl() directly.