docs: clarify predictor request flow and box formats

[Bortlesboat]

Summary

• clarify the README example flow for one-shot video requests vs streamed propagation
• document the box coordinate conventions exposed by the image and video inference APIs
• keep the change limited to the current public contract described by the implementation

Why

Issue #514 calls out ambiguity around the predictor API flow and box coordinate formats. This PR tightens the top-level README so users do not need to inspect the implementation to understand which API streams and which box format each surface returns.

Scope

This is a docs-only clarification PR. It does not change runtime behavior.

Validation

• reviewed the README wording against sam3/model/sam3_base_predictor.py
• reviewed the box-format wording against sam3/model/sam3_image_processor.py and sam3/model/sam3_video_inference.py
• ran git diff --check

[meta-cla]

Hi @Bortlesboat!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[manuelcristianceferinoorue]

La PR que estás viendo en el repositorio de Facebookresearch/Sam3 es puramente documental: no cambia el comportamiento del código en tiempo de ejecución, sino que aclara cómo deben interpretarse los flujos de API y los formatos de cajas devueltos por las superficies de inferencia. Aquí están los puntos clave:

📌 Cambios principales

• Flujos de vídeo

  • Se distingue entre solicitudes one‑shot (procesar un clip completo en una sola llamada) y streaming propagation (procesar frame por frame con propagación de estado).
  • El README ahora explica explícitamente qué ejemplo corresponde a cada caso, para que los usuarios no tengan que inspeccionar la implementación.

• Convenciones de coordenadas de caja

  • Se documenta cómo las APIs de inferencia de imagen y vídeo devuelven las cajas delimitadoras.
  • Esto elimina la ambigüedad sobre si las coordenadas están normalizadas, en píxeles, o qué sistema de referencia usan.

🎯 Alcance

• Es una aclaración documental: no modifica el contrato público ni la lógica interna.
• El objetivo es que los usuarios comprendan los formatos de entrada/salida sin necesidad de leer el código fuente.

✅ Validación

• La redacción del README se contrastó con:
  • sam3/model/sam3_base_predictor.py
  • sam3/model/sam3_image_processor.py
  • sam3/model/sam3_video_inference.py
• Se verificó con git diff --check para asegurar consistencia.

En resumen: esta PR (#519) responde a la ambigüedad señalada en el issue #514 y busca que el README sea autoexplicativo respecto a los flujos de inferencia y las convenciones de cajas, manteniendo intacto el comportamiento del modelo. [github.com](#519)

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!