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.
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) |