get_best_level_for_downsample unintuitive behavior

[jxu]

Context

Issue type (bug report or feature request): Feature request
Operating system (e.g. Fedora 24, Mac OS 10.11, Windows 10): RHEL 7.6
Platform (e.g. 64-bit x86, 32-bit ARM): x86_64
OpenSlide version: 3.4.1
Slide format (e.g. SVS, NDPI, MRXS): SVS

Details

get_best_level_for_downsample has very little documentation on what it actually does.

In https://openslide.org/api/openslide_8h.html, the official API, it says

Get the best level to use for displaying the given downsample.

so I assume it'll find the level that gives the closest downsample level to what user specified.
But it's not clear what method it uses.

For example I have an image with the level_downsamples: (1.0, 4.000338983050847, 16.003617096842103, 64.08332759265456)
and I specify get_best_level_for_downsample(64) which returns level 2, corresponding to a downsample of 16.0036.

From source code it looks like it just chooses the largest level with a downsample less than user's downsample. This should be documented.

openslide/src/openslide.c

Lines 426 to 446 in f55a3bf

	int32_t openslide_get_best_level_for_downsample(openslide_t *osr,
	double downsample) {
	if (openslide_get_error(osr)) {
	return -1;
	}
	// too small, return first
	if (downsample < osr->levels[0]->downsample) {
	return 0;
	}
	// find where we are in the middle
	for (int32_t i = 1; i < osr->level_count; i++) {
	if (downsample < osr->levels[i]->downsample) {
	return i - 1;
	}
	}
	// too big, return last
	return osr->level_count - 1;
	}