[Image] Automatic scaling/thumbnailing of iOS images; resolves "Best Camera Roll Image" documentation discrepancy.

[aroth]

Currently, documentation under "Image > Best Camera Roll Image" is
misleading:

“iOS saves multiple sizes for the same image in your Camera Roll, it is
very important to pick the one that's as close as possible for
performance reasons. You wouldn't want to use the full quality
3264x2448 image as source when displaying a 200x200 thumbnail. If
there's an exact match, React Native will pick it, otherwise it's going
to use the first one that's at least 50% bigger in order to avoid blur
when resizing from a close size. All of this is done by default so you
don't have to worry about writing the tedious (and error prone) code to
do it yourself.”

https://facebook.github.io/react-native/docs/image.html

This does not occur. Instead, React Native loads the full resolution
image no matter the desired size. This means an 8MP photo will require
32MB of memory to display even if displayed in a 100x100 thumbnail.
Loading a series of large images will spike memory and likely crash
your app.

This commit resolves the discrepancy and brings the codebase inline
with current documentation.

Example: Consider a 3264x2448 image loaded on an iPhone 6 with the
following tag:

<Image src={{ uri: 'assets-library://... }} style={{ width: 320,
height: 240 }}/>

The image will automatically be scaled to 640x320 (320x240 target
dimensions * a Retina scale of 2.0). This uses considerably less memory
than rendering the full resolution asset. It also happens automatically.

To force the loading of full resolution, the assetUseMaximumSize option
can be passed in:

<Image src={{ uri: 'assets-library://...', options: {
assetUseMaximumSize: true } }} style={{ width: 320, height: 240 }}/>

Additionally, RCTImageLoader has been updated to handle automatic
scaling for images from both the Assets Library and Photos Framework.

Added an example to UIExplorer. Tap an image in the .

Issues touched:
#1567
#1845
#1579
#930

Note:

Pull Request #1704 (#1704)
takes an alternate approach by allowing an assetThumbnail prop
(boolean) to be passed in to the Image tag's source hash. IE:

<Image src={{ uri: ..., assetThumbnail: true }} />

If true, the asset's thumbnail representation will be used. The
resolution of this thumbnail is non-configurable and does not scale
well.

[sahrens]

Hmm, I thought the documentation was pretty accurate, and the implementation used the actual layout dimensions of the image to grab the optimal size, although I don't think it did any dynamic resizing, just picked the best option the OS has available, but perhaps something broke, or there is a discrepancy with our internal modules...

Anyway, we definitely don't want to be loading giant images when using thumbnails.

[sahrens]

Nick: can you take a look at this since you're refactoring some of our image stuff right now?

[nicklockwood]

@sahrens, we were using different implementations internally and in OSS. The OSS one wasn't doing any scaling, but the internal one was, and I've now merged them.

This PR is going to conflict pretty heavily with the changes I landed today, but the examples look nice, and there are some features exposed on PhotoKit that we don't have yet.

@aroth can you try to rebase after my changes land on github later today? If it turns out to be too hard, or you don't have time, I'll see if I can manually pick in the stuff that's worth keeping. Thanks!

[aroth]

@nicklockwood Thanks. I suspected differences between internal & OSS implementations. I'll attempt a rebase once the changes land.

[aroth]

@nicklockwood Closed, created #2008 with enhancements.