[guarin]

What does this PR do?

Adds a new return_segmentation_scores: bool = False argument to all post_process_semantic_segmentation methods. If True, the method will return segmentation maps and scores. If False, only the segmentation maps are returned.

This changes the return type from all post_process_semantic_segmentation methods from:

-> list[Tensor]

to

-> list[Tensor] | list[SemanticSegmentationPostProcessorOutput]

SemanticSegmentationPostProcessorOutput is a new addition based on BatchFeature and is intended to be used as return type from post_process methods instead of the untyped dicts that we currently return. The class is fully backwards compatible with dict.

Fixes # (issue)

Code Agent Policy

The Transformers repo is currently being overwhelmed by a large number of PRs and issue comments written by
code agents. We are currently bottlenecked by our ability to review and respond to them. As a result,
we ask that new users do not submit pure code agent PRs at this time.
You may use code agents in drafting or to help you diagnose issues. We'd also ask autonomous "OpenClaw"-like agents
not to open any PRs or issues for the moment.

PRs that appear to be fully agent-written will probably be closed without review, and we may block users who do this
repeatedly or maliciously.

This is a rapidly-evolving situation that's causing significant shockwaves in the open-source community. As a result,
this policy is likely to be updated regularly in the near future. For more information, please read CONTRIBUTING.md.

• I confirm that this is not a pure code agent PR.

Before submitting

• This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
• Did you read the contributor guideline,
  Pull Request section?
• Was this discussed/approved via a Github issue or the forum? Please add a link
  to it if that's the case.
• Did you make sure to update the documentation with your changes? Here are the
  documentation guidelines, and
  here are tips on formatting docstrings.
• Did you write any new necessary tests?

Who can review?

Anyone in the community is free to review the PR once the tests have passed. Feel free to tag
members/contributors who may be interested in your PR.

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[Rocketknight1]

cc @molbap @yonigozlan @NielsRogge, not sure if anyone's working on this already

[Rocketknight1]

Oop, didn't realize @guarin was working here! No insult intended 😅

[molbap]

Looks nice! it's a new API design so let's think a bit but to me it can get out of drafts and be reviewed. I tried it on an old/small model, it works well and should allow a nice use by downstream libs.

[vasqu]

Honestly @molbap found the important stuff imo. The hardest part here is the naming and convention 😬

[Leev1s]

Following the discussion above, I agree that return_logits may be too narrow here, and that return_scores / segmentation_scores better describes the tensor this PR is trying to expose.

A related design point from #46139: I think this PR also exposes a broader gap in semantic segmentation APIs.

Today, each model/image processor owns its own post-processing path. That makes sense for model-specific restoration, but for users working across models within the same task, it creates extra learning cost: every model family may expose a slightly different final tensor, naming convention, and hard-decision rule.

So beyond the immediate naming issue, I wonder if a longer-term direction could be a task-oriented post-processing layer for semantic segmentation. In that design, each processor would still handle model-specific restoration, but would expose a shared pre-final score interface before the hard segmentation map is produced.

This kind of unified layer would also give external decoding methods a clearer place to fit. For example, RankSEG-style decoding does not need to change the model or preprocessing; it only replaces the final hard-decision step with a metric-aware decoding method. So it could naturally sit on top of this shared post-processing interface: reuse the official Transformers restoration path, then apply an alternative task-level decoder.

Not suggesting that this PR needs to solve the whole abstraction now, but I think the current naming/API discussion is a useful first step toward that direction.

[molbap]

Thanks for iterating! I think this can get out of "draft" mode at this point haha

[guarin]

@Leev1s that's a valid concern! Definitely too much for this PR but something to keep in mind for the future. We'll have to see how much user interest there is for this feature. Making all possible outputs configurable will increase the number of arguments and code branching quite a bit.

[Leev1s]

@guarin Thanks for the response.🤗

The reason I'm still pushing a bit on this is that the current implementation makes return_segmentation_scores=True look like a score-output path, but internally it still always runs the final hard-decision step first. For downstream decoders, that means the official restoration path is available, but not quite as a clean scores-only entry point yet.

I think a paired opt-in flag keeps the current PR's default behavior unchanged while making the separation explicit:

return_segmentation_scores=True
return_segmentation=False

would return restored scores with segmentation=None, and skip the final argmax / thresholding step. So the default path stays exactly as-is, but downstream methods that only need scores don't pay for or depend on the hard map.

[Leev1s]

@guarin

Sent a small follow-up PR to make the scores-only decoder contract concrete.

[guarin]

@Leev1s the current pattern with return_segmentation_scores is consistent with other similar flags in transformers like return_loss that "add" an extra output to the default outputs. To make individual outputs fully configurable, and avoid any extra computation, we'll have to look beyond semantic segmentation and take other models and tasks into account to keep the functionalities consistent across the whole codebase. This will require more consideration and we'll have to see how much user interest there is for such a feature.

Do you have a particular use-case that benefits from excluding the segmentation computation completely that goes beyond the minor speed-up due to skipping the extra argmax computation?

[vasqu]

Pretty satisfied with the current state. Just a few last comments from my side

[stevhliu]

thanks for adding docs! just a few minor nits :)

[github-actions]

[For maintainers] Suggested jobs to run (before merge)

run-slow: beit, chmv2, conditional_detr, deformable_detr, detr, dpt, eomt, grounding_dino, mask2former, maskformer, mobilenet_v2, mobilevit, oneformer, sam3, sapiens2, segformer