I have two short questions about overlays. To clarify, let me start
with a short motivation.

I have been working on some alternative 'display engine' (I hope I am
using a somewhat correct term here).  Of course, I would prefer to
make functions reusable if possible (currently, image-dired, doc-view,
pdf-tools, and dvju all 'implemented their own' display engines). A
demonstration can be found in the animated gif for the 'universal
document reader' here <https://github.com/dalanicolai/doc-tools> (I would
prefer to reuse/contribute to
doc-view/tools, but it turns out to be much easier to start from
scratch and, if possible, port things over. That simultaneously cleans
up that code).

The 'essence' of that document reader is a very simple 'overlay grid',
which I like to provide as a 'reusable function' (the idea is very
simple and an example is provided in the following file . To try it,
you can simply load the code and show images from a directory by doing
M-x scrap-dir-images. I am not trying to replace image-dired. The
function is just an easy way to implement an example. Also the name
scrap comes from 'scrapbook', but I guess I could simply call it
overlay-grid. Let me know if you have some idea about the naming).

I have been using the overlay grid already in image-roll
<https://github.com/dalanicolai/image-roll.el>, but later I
'discovered' a much simpler way to implement the logic for
'dynamically updating' of visible overlays (i.e. pages, for 'normal
page sizes' we can not display all images of a document at
simultaneously), by simply using the 'overlays-in' function in a
'clever' (or actually quite straightforward) way (instead of
reimplementing that same functionality in lisp).

So now here are the questions:

- when displaying multiple pages in columns, I would like to use the
overlays-in function to determine which overlays should display
images.  So I am creating a full 'book roll' by giving the overlays a
size via the 'space' display property
<https://www.gnu.org/software/emacs/manual/html_node/elisp/Specified-Space.html>,
after which I use overlays-in
to determine which overlays are actually visible. However, after it
takes some time for the 'space' display property to take effect, so I
am manuall adding a 'sit-for' with some reasonable delay
time. However, I would like to ask if there is someone has an idea for
a 'better' mechanism to wait until/detect if the 'overlay expansion'
has finished.

If the explanation is not clear then please load the following file
and do 'M-x scrap-dir-images' on a directory that contains enough
images to not fit all on a single screen. It will print the number of
overlays found via 'overlays-in' directly after 'displaying the
images' (here by assigning the image as display property instead of
space). You will find it prints all overlays in the buffer (instead of
only the ones on screen). To find what I expect it to print now
(again) do 'M-: (overlays-in (window-start) (window-end))'.

My second question is about the function 'overlay-recenter' I don't
really understand its docstring. What kind of 'overlay lookup' would
go faster? What is 'overlay-lookup' anyway?

I hope that some experts here could clear things up in a few words (as
usually is the case :)

Thanks!