Sign in Get started

Search

Find visually similar images by embedding, or images whose auto-tags match objects, scenes and attributes, in one dataset or your whole organization. Free.

View as Markdown
On this page

Embeddings and auto-tags are computed at upload. An image uploaded with embed=False has neither until backfill_embeddings computes them.

by_similarity

Images that look like a reference image, searched in its directory by default.

Source: Search.by_similarity

Arg Type Default Notes
dataset str required Dataset name or id
image str required Reference image path (addressing)
threshold float 0.6 Minimum cosine similarity; 0.6 is roughly “visually related”
limit int 50 Max results (up to 500)
directory str | None None Directory to search (default: the reference image’s); "" searches the whole dataset, "/" only the root
results = client.search.by_similarity(
    dataset="road-signs",
    image="stop-sign-0421.jpg",
    threshold=0.6,
    limit=50,
)
for r in results:
    print(r.path, f"{r.similarity:.3f}")  # r.path is each result's address
pictograph search similar road-signs stop-sign-0421.jpg --threshold 0.6 -n 50
curl -s "https://api.pictograph.io/api/v1/developer/search/similar?dataset=road-signs&image=stop-sign-0421.jpg&threshold=0.6&limit=50" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[SimilarImage]

SimilarImage · 7 fields
class SimilarImage(BaseModel):
    """One result from pictograph.resources.search.Search.by_similarity."""
    id: str
    filename: str
    # Its directory in the dataset.
    directory_path: str = '/'
    status: Literal['new', 'annotate', 'review', 'complete']
    annotation_count: int
    # Its auto-tags, by kind: objects, scenes and attributes.
    auto_tags: dict[str, Any] = {}
    similarity: float

    # The image's address in its dataset - pass it as `image` to any per-image call.
    @property
    def path(self) -> str: ...

by_tag

Images carrying every tag you list, within a category and across them. Give at least one of objects, scenes or attributes.

Source: Search.by_tag

Arg Type Default Notes
objects Sequence[str] | None None Object tags to match, e.g. car
scenes Sequence[str] | None None Scene tags to match, e.g. highway
attributes Sequence[str] | None None Attribute tags to match, e.g. night
dataset str | None None Dataset name or id; None searches the whole organization
limit int 50 Max results (up to 500)
offset int 0 Items to skip
results = client.search.by_tag(
    objects=["car", "truck"],
    scenes=["highway"],
    attributes=["night"],
    dataset="my-dataset",
    limit=100,
)
for r in results:
    print(r.id, r.auto_tags["objects"])
pictograph search tags \
  --object car --object truck \
  --scene highway \
  --attribute night \
  --dataset my-dataset -n 100
curl -s "https://api.pictograph.io/api/v1/developer/search/by-tags?objects=car&objects=truck&scenes=highway&attributes=night&dataset=my-dataset&limit=100" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[TaggedImage]

TaggedImage · 7 fields
class TaggedImage(BaseModel):
    """One result from pictograph.resources.search.Search.by_tag."""
    id: str
    dataset_id: str
    filename: str
    # Its directory in the dataset.
    directory_path: str = '/'
    status: Literal['new', 'annotate', 'review', 'complete']
    annotation_count: int
    # Its auto-tags, by kind: objects, scenes and attributes.
    auto_tags: dict[str, Any] = {}

    # The image's address in its dataset - pass it as `image` to any per-image call.
    @property
    def path(self) -> str: ...

Auto-tag taxonomy

Images are tagged from a fixed list of 218 objects, 44 scenes and 67 attributes; a tag outside the list never matches. Examples:

  • objects: car, truck, person, bicycle, dog, …
  • scenes: highway, parking lot, office, beach, construction site, …
  • attributes: night, fog, rain, aerial view, close-up, …

Common errors

Status Exception Cause
404 NotFoundError The reference image or dataset doesn’t exist in your organization
- ValueError by_tag with no objects, scenes or attributes, raised before sending (REST answers 400)
Copied to clipboard