Enum Span 

pub enum Span {
    Text {
        start: usize,
        end: usize,
    },
    BoundingBox {
        x: f32,
        y: f32,
        width: f32,
        height: f32,
        page: Option<u32>,
    },
    Hybrid {
        start: usize,
        end: usize,
        bbox: Box<Span>,
    },
}

A span locator for text and visual modalities.

Span is a simplified subset of grounded::Location designed for the detection layer (Entity). It covers the most common cases:

• Text offsets (traditional NER)
• Bounding boxes (visual document understanding)
• Hybrid (OCR with both text and visual location)

Relationship to Location

Span variant	Location equivalent
Text	Location::Text
BoundingBox	Location::BoundingBox
Hybrid	Location::TextWithBbox

For modalities not covered by Span (temporal, cuboid, genomic, discontinuous), use Location directly via the canonical Signal → Track → Identity pipeline.

Conversion

• Span → Location: Always succeeds via Location::from(&span)
• Location → Span: Use location.to_span(), returns None for unsupported variants

Variants

Text

Text span with character offsets (start, end).

Offsets are Unicode scalar value indices (what text.chars() counts), consistent with Entity.start/end and grounded::Location::Text.

Fields

start: usize

Start character offset (inclusive)

end: usize

End character offset (exclusive)

BoundingBox

Visual bounding box (normalized 0.0-1.0 coordinates) For ColPali: image patch locations

Fields

x: f32

X coordinate (normalized 0.0-1.0)

y: f32

Y coordinate (normalized 0.0-1.0)

width: f32

Width (normalized 0.0-1.0)

height: f32

Height (normalized 0.0-1.0)

page: Option<u32>

Optional page number (for multi-page documents)

Hybrid

Hybrid: both text and visual location (for OCR-verified extraction)

Fields

start: usize

Start character offset (inclusive)

end: usize

End character offset (exclusive)

bbox: Box<Span>

Bounding box for visual location

Implementations

impl Span

pub const fn text(start: usize, end: usize) -> Span

Create a text span.

pub fn bbox(x: f32, y: f32, width: f32, height: f32) -> Span

Create a bounding box span with normalized coordinates.

pub fn bbox_on_page(x: f32, y: f32, width: f32, height: f32, page: u32) -> Span

Create a bounding box with page number.

pub const fn is_text(&self) -> bool

Check if this is a text span.

pub const fn is_visual(&self) -> bool

Check if this has visual location.

pub const fn text_offsets(&self) -> Option<(usize, usize)>

Get text offsets if available.

pub fn len(&self) -> usize

Calculate span length for text spans.

pub fn is_empty(&self) -> bool

Check if span is empty.

Trait Implementations

impl Clone for Span

fn clone(&self) -> Span

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Span

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Span

fn default() -> Span

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Span

fn deserialize<__D>( __deserializer: __D, ) -> Result<Span, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&Span> for Location

fn from(span: &Span) -> Location

Converts to this type from the input type.

impl From<Span> for Location

fn from(span: Span) -> Location

Converts to this type from the input type.

impl PartialEq for Span

fn eq(&self, other: &Span) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Span

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Span