tlc.schemas

Built-in schemas for describing 3LC table columns.

This package gathers the curated, user-facing schema classes. Power users authoring custom schemas should reach for tlc.Schema directly. Scalar value descriptors (Int32Value, Float32Value, DimensionNumericValue, StringValue, DictValue, …) live in the tlc.schemas.values submodule and are accessed as tlc.schemas.values.Int32Value etc.

Modules and Packages

Module

Description

values

Scalar value descriptors used by tlc.Schema.

Package Contents

Classes

Class

Description

BoolSchema

Schema for boolean data.

CategoricalLabelListSchema

Variable-length list of categorical labels. Equivalent to CategoricalLabelSchema(shape=(-1,)).

CategoricalLabelSchema

Schema for a categorical label.

ConfidenceSchema

Schema for a model confidence value in the [0, 1] range.

DatetimeStringSchema

Schema for datetime strings. Equivalent to StringSchema(string_role="Datetime").

EmbeddingSchema

Schema for neural-network embedding vectors.

EpochSchema

A schema for epoch values.

ExampleIdSchema

A schema for example ID values.

ExternalNumpyArraySchema

Schema for numpy arrays stored as one .npy file per row.

ExternalTorchTensorSchema

Schema for PyTorch tensors stored as one .pt file per row.

Float32ListSchema

Variable-length 1D float32 array. Equivalent to Float32Schema(shape=(-1,)).

Float32Schema

Schema for float32 data.

Float64Schema

Schema for float64 data.

ForeignTableIdSchema

A schema describing a value that identifies a foreign table.

FractionSchema

Schema for a float value in the [0, 1] range.

ImageSchema

Schema for image columns. One class, four behaviors via sample_type.

Int16Schema

Schema for int16 data.

Int32Schema

Schema for int32 data.

Int64Schema

Schema for int64 data.

Int8Schema

Schema for int8 data.

IoUSchema

Schema for an intersection-over-union value in the [0, 1] range.

IterationSchema

A schema for iteration values.

MapElement

Defines a single item in a value map.

ProbabilitySchema

Schema for a probability value in the [0, 1] range.

SampleWeightSchema

A schema for sample weight values.

SemanticSegmentationSchema

Schema for semantic segmentation PIL Image data.

StringSchema

Schema for string data.

Uint16Schema

Schema for uint16 data.

Uint32Schema

Schema for uint32 data.

Uint64Schema

Schema for uint64 data.

Uint8Schema

Schema for uint8 data.

UnixTimestampSchema

Schema for int64 Unix timestamps.

UrlSchema

Schema for URL strings.

VideoUrlSchema

Schema for video URL references.

API

class BoolSchema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for boolean data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class CategoricalLabelListSchema(
classes: str | Sequence[str] | Sequence[dict[str, str]] | Sequence[MapElement] | dict[float, str] | dict[int, str] | dict[float, MapElement] | dict[int, MapElement] | None = None,
*,
list_size: int | None = None,
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._categorical_schemas.CategoricalLabelSchema

Variable-length list of categorical labels. Equivalent to CategoricalLabelSchema(shape=(-1,)).

Parameters:

  • classes – Class labels. Accepts a list of names (0-indexed), a dict mapping numeric keys to names or MapElements, or a single class name string. None or empty for no classes.

  • list_size – Fixed list length. None for variable-length lists.

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class CategoricalLabelSchema(
classes: str | Sequence[str] | Sequence[dict[str, str]] | Sequence[MapElement] | dict[float, str] | dict[int, str] | dict[float, MapElement] | dict[int, MapElement] | None = None,
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for a categorical label.

Values are stored as int32 with an associated class map. The number_role is always "label".

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • classes – Class labels. Accepts a list of names (0-indexed), a dict mapping numeric keys to names or MapElements, or a single class name string. None or empty for no classes.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class ConfidenceSchema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
description: str = '',
writable: bool = False,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
)

Bases: tlc.schemas._metric_schemas.FractionSchema

Schema for a model confidence value in the [0, 1] range.

Bakes number_role="fraction/confidence" for the Dashboard’s confidence color treatment.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard. Defaults to False since metric values are typically computed.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class DatetimeStringSchema(
*,
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
)

Bases: tlc.schemas._primitive_schemas.StringSchema

Schema for datetime strings. Equivalent to StringSchema(string_role="Datetime").

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class EmbeddingSchema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
description: str = '',
writable: bool = False,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._primitive_schemas.Float32Schema

Schema for neural-network embedding vectors.

Bakes number_role="nn_embedding" (enables UMAP/dim-reduction hooks and hides the column in the Dashboard) and writable=False.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Embedding dimensions — e.g. shape=512 or shape=(512,).

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard. Defaults to False since embeddings are model outputs.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class EpochSchema(
*,
display_name: str = 'Epoch',
description: str = 'Epoch of training',
display_importance: float | None = None,
)

Bases: tlc.schemas._schema.Schema

A schema for epoch values.

Always non-writable since the epoch is recorded by the training loop and shouldn’t be edited by hand.

Parameters:

  • display_name – Column display name in the Dashboard.

  • description – Column description.

  • display_importance – Ordering weight for column display (higher = more prominent). None uses the default epoch display importance.

class ExampleIdSchema(
*,
display_name: str = 'Example ID',
description: str = '',
writable: bool = False,
computable: bool = False,
)

Bases: tlc.schemas._schema.Schema

A schema for example ID values.

Example ID is a unique identifier for an example. It is used to identify examples across different tables. Defaults to writable=False since the ID is structural and shouldn’t be edited by hand.

Parameters:

  • display_name – Column display name in the Dashboard.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • computable – Whether the column is computable from other columns.

class ExternalNumpyArraySchema(
*,
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
bulk_data_location: str | Url | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for numpy arrays stored as one .npy file per row.

The row value is a URL pointing to the file. In sample view, values are converted to/from numpy.ndarray by loading the referenced file. Shape and dtype are determined by the stored file; for inline numpy sample view, use Float32Schema (or another primitive) with sample_type="numpy_array".

Parameters:

  • display_name – Column display name in the Dashboard.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • bulk_data_location – URL override for bulk data storage.

class ExternalTorchTensorSchema(
*,
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
bulk_data_location: str | Url | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for PyTorch tensors stored as one .pt file per row.

The row value is a URL pointing to the file. In sample view, values are converted to/from torch.Tensor by loading the referenced file. Shape and dtype are determined by the stored file; for inline torch sample view, use Float32Schema (or another primitive) with sample_type="torch_tensor".

Parameters:

  • display_name – Column display name in the Dashboard.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • bulk_data_location – URL override for bulk data storage.

class Float32ListSchema(
*,
list_size: int | None = None,
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._primitive_schemas.Float32Schema

Variable-length 1D float32 array. Equivalent to Float32Schema(shape=(-1,)).

For roled list columns prefer the baked schema with a list shape (e.g. ConfidenceSchema(shape=(-1,))) rather than constructing a raw float list.

Parameters:

  • list_size – Fixed list length. None for variable-length lists.

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Float32Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for float32 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions. Examples: shape=10 (fixed list of 10), shape=(-1,) (variable list), shape=(-1, -1) (variable 2D).

  • number_role – Escape hatch for UI roles without a baked schema. Prefer EmbeddingSchema for embeddings and FractionSchema for [0, 1] values (fraction / confidence / probability / iou). Defaults to no role.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Float64Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for float64 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Float32Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class ForeignTableIdSchema(
foreign_table_url: str,
*,
display_name: str = '',
)

Bases: tlc.schemas._schema.Schema

A schema describing a value that identifies a foreign table.

Always non-writable since the reference is part of the table’s structure, not user-editable data.

Parameters:

  • foreign_table_url – URL of the foreign table this column references.

  • display_name – Display name for the mapped value. If empty, the Dashboard derives one from the URL.

class FractionSchema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
description: str = '',
writable: bool = False,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for a float value in the [0, 1] range.

Defaults to writable=False since metric values are typically computed, not authored. For semantically specialized variants with their own Dashboard color treatment, use ConfidenceSchema, ProbabilitySchema, or IoUSchema.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard. Defaults to False since metric values are typically computed.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class ImageSchema(
*,
display_name: str = '',
sample_type: Literal[pil_png, pil_jpeg, pil_webp, url] | None = 'pil_png',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
bulk_data_location: str | Url | None = None,
metadata: dict[str, Any] | None = None,
number_role_u: str | None = None,
number_role_v: str | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for image columns. One class, four behaviors via sample_type.

Wire format is identical for all modes — a string URL pointing at an image file (ImageUrlStringValue). What varies is what the column accepts on write and returns on read.

sample_type

Write input

Sample view returns

"pil_png" (default)

PIL.Image or URL string

PIL.Image (load from URL)

"pil_jpeg"

PIL.Image or URL string

PIL.Image

"pil_webp"

PIL.Image or URL string

PIL.Image

"url"

URL string

URL string (passthrough)

The three pil_* variants differ only in the encoding used when externalizing in-memory PIL images to disk; load() is format-agnostic, so the read side is interchangeable. They also accept URL strings on write — already-stored images pass through verbatim, with no decode/re-encode. The "url" mode disables PIL handling entirely — both write and read are URL passthroughs — and is the schema for columns that reference pre-existing image files (e.g. an authored dataset).

Example::

# PIL images serialized as PNG (default)
ImageSchema()

# PIL images serialized as JPEG
ImageSchema(sample_type="pil_jpeg")

# URL passthrough — pre-existing image files referenced by path
ImageSchema(sample_type="url")
Parameters:

  • display_name – Column display name in the Dashboard.

  • sample_type – Selects the column’s behavior. See the class docstring for the full table. "pil_png"/"pil_jpeg"/"pil_webp" write PIL images to disk in the named format (and pass through URL strings unchanged). "url" is full URL passthrough — accepts and returns URL strings unchanged, with no PIL handling on either side. None is accepted as an alias for "url".

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • bulk_data_location – URL override for bulk data storage. Has no effect when sample_type=None (no files are written in that mode).

  • metadata – Arbitrary key-value metadata attached to this schema element.

  • number_role_u – Tag for the horizontal (U) axis. Image columns that share the same number_role_u/number_role_v pair get linked cursor and zoom in the Dashboard, so panning or zooming one image moves the others in lockstep.

  • number_role_v – Tag for the vertical (V) axis. See number_role_u.

class Int16Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for int16 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Int8Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Int32Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for int32 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Int8Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Int64Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for int64 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Int8Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Int8Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for int8 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. Prefer CategoricalLabelSchema for label columns. Defaults to no role.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class IoUSchema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
description: str = '',
writable: bool = False,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
)

Bases: tlc.schemas._metric_schemas.FractionSchema

Schema for an intersection-over-union value in the [0, 1] range.

Bakes number_role="fraction/iou" for the Dashboard’s IoU color treatment.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard. Defaults to False since metric values are typically computed.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class IterationSchema(
*,
display_name: str = 'Iteration',
description: str = 'The current iteration of the training process.',
display_importance: float | None = None,
)

Bases: tlc.schemas._schema.Schema

A schema for iteration values.

Always non-writable since the iteration is recorded by the training loop and shouldn’t be edited by hand.

Parameters:

  • display_name – Column display name in the Dashboard.

  • description – Column description.

  • display_importance – Ordering weight for column display (higher = more prominent). None uses the default iteration display importance.

class MapElement(
internal_name: str = '',
*,
display_name: str = '',
description: str = '',
display_color: str = '',
url: str = '',
)

Bases: dict

Defines a single item in a value map.

Initialize self. See help(type(self)) for accurate signature.

property description: str
property display_color: str
property display_name: str
static from_any(
any_map_element: Any,
) → MapElement

Creates a MapElement object and populates it from an anonymous, possibly sparse object

property internal_name: str
to_minimal_dict(
include_all: bool,
) → dict[str, Any]

Add a minimal representation of this object to a dictionary for subsequent serialization to JSON

property url: str
class ProbabilitySchema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
description: str = '',
writable: bool = False,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
)

Bases: tlc.schemas._metric_schemas.FractionSchema

Schema for a probability value in the [0, 1] range.

Bakes number_role="fraction/probability" for the Dashboard’s probability color treatment.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard. Defaults to False since metric values are typically computed.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class SampleWeightSchema(
*,
display_name: str = 'Weight',
description: str = 'The weights of the samples in this table.',
sample_type: str = 'hidden',
default_value: float = 1.0,
)

Bases: tlc.schemas._schema.Schema

A schema for sample weight values.

Parameters:

  • display_name – Column display name in the Dashboard.

  • description – Column description.

  • sample_type – Override the sample type. "hidden" hides the column from sample view.

  • default_value – Default weight for new rows.

class SemanticSegmentationSchema(
*,
display_name: str = '',
classes: str | Sequence[str] | Sequence[dict[str, str]] | Sequence[MapElement] | dict[float, str] | dict[int, str] | dict[float, MapElement] | dict[int, MapElement] = (),
sample_type: Literal[pil_png, pil_jpeg, pil_webp] = 'pil_png',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
bulk_data_location: str | Url | None = None,
metadata: dict[str, Any] | None = None,
number_role_u: str | None = None,
number_role_v: str | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for semantic segmentation PIL Image data.

A single-channel PIL image containing a semantic segmentation mask where pixel values correspond to class labels. The class map is used as-is: if you want a background class at pixel value 0, include it explicitly in the class list or dict.

Example::

# Background at index 0, cat at 1, dog at 2
SemanticSegmentationSchema(classes=["background", "cat", "dog"])

# Equivalent using a dict
SemanticSegmentationSchema(classes={0: "background", 1: "cat", 2: "dog"})
Parameters:

  • display_name – Column display name in the Dashboard.

  • classes – Class labels for segmentation. Accepts a list of class names (0-indexed), a dict mapping numeric keys to class names or MapElements, or a single class name string.

  • sample_type – File-encoding format. "pil_png" (default) is lossless and supports palette/grayscale modes natively, which is usually what you want for segmentation masks. "pil_jpeg" and "pil_webp" are available but lossy and may corrupt label values.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • bulk_data_location – URL override for bulk data storage.

  • metadata – Arbitrary key-value metadata attached to this schema element.

  • number_role_u – Tag for the horizontal (U) axis. Mask columns that share the same number_role_u/number_role_v pair as an image column get linked cursor and zoom in the Dashboard, so panning or zooming the image moves the overlay in lockstep.

  • number_role_v – Tag for the vertical (V) axis. See number_role_u.

class StringSchema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
string_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
bulk_data_location: Url | str | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for string data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • string_role – Escape hatch for UI roles without a baked schema. Prefer UrlSchema for URLs and DatetimeStringSchema for datetime strings. Defaults to no role.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

  • bulk_data_location – URL or path prefix where bulk data files are stored for this column. When set, the TableWriter externalizes column data to files under this location.

class Uint16Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for uint16 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Int8Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Uint32Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for uint32 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Int8Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Uint64Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for uint64 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Int8Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class Uint8Schema(
*,
display_name: str = '',
shape: tuple[int, ...] | int | None = None,
number_role: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden, numpy_array, torch_tensor] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for uint8 data.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • shape – Dimensions of the data. None for scalar, int or tuple for arrays. Use -1 for variable-size dimensions.

  • number_role – Escape hatch for UI roles without a baked schema. See Int8Schema.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class UnixTimestampSchema(
*,
precision: Literal[s, ms, us, ns],
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for int64 Unix timestamps.

Stores time since the Unix epoch (1970-01-01 UTC) at the precision selected by precision. Precision is required — choose it to match your source data:

  • "s" — whole seconds. Output of int(time.time()).

  • "ms" — milliseconds. Convention used by JavaScript Date.now() and most JSON APIs.

  • "us" — microseconds. Resolution of Python datetime and Arrow timestamp[us].

  • "ns" — nanoseconds. Resolution of pandas Timestamp and Arrow timestamp[ns].

Parameters:

  • precision – Time unit of the stored integer. See the class docstring for the conventions each value matches.

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

class UrlSchema(
*,
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
sample_type: Literal[hidden] | None = None,
bulk_data_location: Url | str | None = None,
)

Bases: tlc.schemas._primitive_schemas.StringSchema

Schema for URL strings.

The stored value is a plain string, but the URL role enables automatic path aliasing and relativization, and signals to the Dashboard that the value refers to an external file.

Parameters:

  • display_name – Column display name in the Dashboard. Also used as column key in tuple shorthand.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • sample_type – Override the sample type. None means identity (no transform), "hidden" hides from sample view.

  • bulk_data_location – URL or path prefix where bulk data files are stored for this column. When set, the TableWriter externalizes column data to files under this location.

class VideoUrlSchema(
*,
display_name: str = '',
description: str = '',
writable: bool = True,
default_visible: bool = True,
default_value: Any = None,
metadata: dict[str, Any] | None = None,
number_role_u: str | None = None,
number_role_v: str | None = None,
)

Bases: tlc.schemas._schema.Schema

Schema for video URL references.

Stores URL strings pointing to existing video files.

Parameters:

  • display_name – Column display name in the Dashboard.

  • description – Column description.

  • writable – Whether the column is editable in the Dashboard.

  • default_visible – Whether the column is visible by default.

  • default_value – Default value for new rows.

  • metadata – Arbitrary key-value metadata attached to this schema element.

  • number_role_u – Tag for the horizontal (U) axis. Image columns that share the same number_role_u/number_role_v pair get linked cursor and zoom in the Dashboard, so panning or zooming one image moves the others in lockstep.

  • number_role_v – Tag for the vertical (V) axis. See number_role_u.