Sexual assault returns a seriously bad selection. The image is a living young woman which, when used as PageImage paired with the page title, looks BADLY like she was just Sexually Assaulted moments ago.
Jyllands-Posten Muhammad cartoons controversy reaches all the way down to the 15th article section, for the 4th article image, tangentially related, from 700 years ago
Fabia Drake returns an image of Tallulah Bankhead
I don't have a link handy, but there was a biography that not only returned the wrong person, it returned the opposite gender.

PageImage is being used to select a Hero image to "represent the article". Images in subsections are generally very specific to the section-topic and generally are not appropriate to represent the article subject itself.

Wikidata has a better image in the majority of these cases, so your examples only support T95026: PageImages should be able to pick Wikidata's P18 as chosen image.

Wikidata was zero help. Jylland had no image, Fabia Drake returned the SAME wrong image, and Sexual Assault returned an offensively bad carton image. I removed the two bad images from Wikidata.

Still trying to work out how to associate section number with image. PageImages is setup to listen to 3 hooks- AfterParserFetchFileAndTitle, ParserMakeImageParams, AfterParserFetchFileAndTitle and populate a list of images as images are encountered. None of these hooks provide any idea of where in the page the image is. In fact sections are done as an after thought

Right now I'm wondering if this is worth of a complete overhaul where images are extracted inside the OutputPageParserOutput hook by turning $po->mText into a DOMDocument and parsing out the images from the HTML... scary.

PageImages currently listens to 3 hooks which are run when images are processed and added to the page.
At the time these hooks execute, the contents of parser text are not available neither is knowledge of sections.

The sequence of events is

• doHeadings is run converting = characters to heading element markup e.g. == becomes <h2>
• hook BeforeParserFetchFileAndTitle is run
• hook ParserMakeImageParams is executed.
• ParserFileProcessingHookHandlers::processFile is run

I see two ways forward...

1. Move processing to end of save process and convert HTML to a DOMTree and extract images
2. Surface and inspect the parser HTML text.

Option #2 would involve the following post-process step via the ParserAfterParse hook and seems like it would be pretty reliable:

                $pi = $this->getOutput()->getExtensionData( 'pageImages' ) 
		if ( count($pi ) > 0 ) {
			$x = strpos( $text, '<h' ); // index of start of first heading
			$leadImages = [];
			foreach ( $pi as $p ) {
				$y = strpos( $text, $p['filename'] );
				if ( $x < $y ) {
				        // Images are parsed in order of occurance so we can avoid further strpos calls once we've found one beyond the first heading
					break;
				} else {
					$leadimages[] = $p['filename'];
				}
			}
		}
		$po->getOutput()->setExtensionData( 'pageImages', $leadImages )

#2 feels a little hacky but when you get over the fact this is way the parser works, it's not so bad.
#1 seems like a no-go due to performance concerns.

Ideally, we'd be able to avoid parsing those additional pages images. This would need a core change to run a hook after the execution of doHeadings that surfaces the text.

Thoughts needed before I actually go ahead and write any code... so moving to code review.

Maybe, extract section 0 and make a separate parse on it? Gonna be generally faster than #1 on large pages and less fragile than #2.

I'm struggling to find a suitable hook that only runs during a save and that provides access to the HTML of the lead section

Still not found the hook I need but the code is pretty simple once I do:

$poLead = $content->getSection( 0 )->getParserOutput( $article->getTitle() );
$pageImages = $poLead->getExtensionData( 'pageImages' ) ?: [];

This give images only in the lead section.. I'm just not sure which hook to put it in as I'll want to do this at a time I can save the result via setExtensionData

Change 323989 had a related patch set uploaded (by Jdlrobson):
Restrict page images to lead section

https://gerrit.wikimedia.org/r/323989

@ovasileva do we want the switch to act instantaneously? How often are we planning on turning it on and off? If we're going to use the lead section images only in the future, I suggest we remove the requirement that asks to make the feature switchable. This would simplify the implementation. If, however, we want the keep the ability to toggle between modes and want the API return the updated results immediately, then we'd have to do more work on the current patch.

@bmansurov - I am okay with switching to lead section images only completely. While I agree that use cases might exist against this, I haven't been able to identify one yet. If a significant one appears in the future, we can switch then.

If there's no flag and the feature changes the standard response of the API without additional user interaction – in this case, a query parameter – then:

1. It ain't a feature.
2. The third AC should be changed to:

The change shouldn't be merged until it's announced on wikitech-l and mediawiki-api (or mediawiki-api-announce).

We agreed in standup to keep the flag and enable it in a follow up (see extension.json note in the latest commit).

I will start a thread about feature flagging.

@phuedx I've updated T152115 with your suggestion.

Change 323989 merged by jenkins-bot:
Restrict page images to lead section

https://gerrit.wikimedia.org/r/323989

Perhaps you should also test adding an image map outside the lead section and figure out what happens then? There has been a lot of totally counterintuitive behaviour with image maps and page images, so that seems worth testing.

@Deskana, thanks for suggesting good test cases. I think I've found a bug. Basically, imagemaps are ignored when in lead section (last test case below).

• Image in the lead section, image map in the last section: http://reading-web-staging.wmflabs.org/wiki/PageImages3

The API returns the image in the lead section: http://reading-web-staging.wmflabs.org/w/api.php?action=query&prop=pageimages&titles=PageImages3&pithumbsize=100&pilicense=any

• Same as before, but the image map is generated using a parser tag: http://reading-web-staging.wmflabs.org/wiki/PageImages4

The API still returns the image in the lead section: http://reading-web-staging.wmflabs.org/w/api.php?action=query&prop=pageimages&titles=PageImages4&pithumbsize=100&pilicense=any

• Image map in the last section only (no other images on the page): http://reading-web-staging.wmflabs.org/wiki/PageImages5

The API doesn't return any images either: http://reading-web-staging.wmflabs.org/w/api.php?action=query&prop=pageimages&titles=PageImages5&pithumbsize=100&pilicense=any

• Image map in the lead section (no other images on the page): http://reading-web-staging.wmflabs.org/wiki/PageImages6

The API doesn't return the image map, but it should: http://reading-web-staging.wmflabs.org/w/api.php?action=query&prop=pageimages&titles=PageImages6&pithumbsize=100&pilicense=any

@Jdlrobson, do you think we should capture the problem above in a separate task as it's more related to image maps than to the current implementation?

Per T87336#2858587.

This doesn't seem related? When $wgPageImagesLeadSectionOnly = false PageImages6 also doesn't return a pageimage and even if I put the imagemap inside a section it doesn't have one.

It wouldn't surprise me if ImageMaps (given they are provided by an extension) are not monitored by PageImages. There's an argument to be made that they shouldn't but that's a story for another ticket.