Pictograph
Label images, train vision models, run them anywhere.
Docs · Quick start · API reference · App
Four ways in. Same API underneath, so you can move between them.
| Python | pip install pictograph, this repo |
| CLI | pip install "pictograph[cli]" · reference |
| REST | Any language, X-API-Key header · reference |
| Claude skill | Let an agent drive it · guide |
Quick start
pip install pictograph
Upload a directory, label it from a text prompt, train, predict.
from pictograph import AnnotateReport, Client, TrainingRun, UploadReport
client = Client() # reads PICTOGRAPH_API_KEY
uploaded: UploadReport = client.images.upload_from_directory(
dataset_name="road-signs",
directory="./road_signs",
)
print(f"{uploaded.images_uploaded} images uploaded")
labelled: AnnotateReport = client.auto_annotate.dataset(
dataset_name="road-signs",
classes=[("stop_sign", "bbox"), ("yield", "bbox")],
)
print(f"{labelled.annotations_added} annotations added")
client.exports.create(
dataset_name="road-signs",
name="road-signs-v1",
format="pictograph",
include_images=True,
wait=True,
)
run: TrainingRun = client.training.create(
dataset_name="road-signs",
export_name="road-signs-v1",
pipeline_type="yolox",
name="road-signs-detector",
)
print("Trained model:", run.model_id or run.status)
A class is a (name, output_type) pair, where the output type is bbox,
polygon or tag, because auto-annotation has to know what shape to produce.
Training runs on an export, never on a dataset directly: you create the
export, see what went into it, then train that.
The same thing from the shell:
pictograph login
pictograph images upload-directory road-signs ./road_signs
pictograph auto-annotate batch road-signs --images 001.jpg,002.jpg --classes "stop_sign:bbox"
pictograph exports create road-signs --name road-signs-v1 -f pictograph --include-images
pictograph train start road-signs road-signs-v1 --pipeline yolox --gpu a10g
pictograph models download "road-signs-detector" -o ./yolox.onnx
Or over REST:
curl -s https://api.pictograph.io/api/v1/developer/datasets/ \
-H "X-API-Key: $PICTOGRAPH_API_KEY"
Resources are addressed by name everywhere. There are no IDs to look up first.
Typed
Responses are Pydantic models. Failures are typed exceptions.
from pictograph.exceptions import NotFoundError, PaymentRequiredError, RateLimitError
try:
client.datasets.get(name="does-not-exist")
except NotFoundError:
...
Transient failures retry with backoff, and writes carry an idempotency key so a retry cannot apply twice.
Async
Every method has an async twin with the same signature.
import asyncio
from pictograph import AsyncClient
async def main() -> None:
async with AsyncClient() as client:
datasets = await client.datasets.list(limit=5)
print([d.name for d in datasets])
asyncio.run(main())
Run models on your own hardware
from pictograph import get_model
model = get_model(name="signs-detector", task="object_detection")
result = model.predict(image="test.jpg")
Weights download and cache on first use. ONNX, PyTorch, ExecuTorch and TensorRT are supported targets. See local inference.
Agents
pip install "pictograph[agents]"
pictograph agents install-skill --target claude-code
from pictograph.agents import Toolkit
tools = Toolkit(client).as_anthropic_tools() # or .as_openai_tools()
Offline utilities
No network needed, so an existing local dataset can be brought into typed models before uploading anything.
pictograph.formats |
Read and write COCO, YOLO, Pascal VOC |
pictograph.metrics |
Score detections against ground truth by IoU |
pictograph.augment |
Transform images, remapping annotation geometry with them |
pictograph.tile |
Slice images into a grid, clipping annotations per tile |
Documentation
Full reference at pictograph.io/docs.
Quick start · Installation · Authentication · API reference · CLI · Agents · Annotation format · Auto-annotation · Local inference · Deployments · Export conversion · Async client · Error handling · Rate limits
Requires Python 3.10 or newer. Extras: [cli], [agents], [inference],
[torch], [all].
Contributing, security, license
CONTRIBUTING.md has the development setup and the checks a change must pass. Report vulnerabilities per SECURITY.md, not as a public issue.
The SDK is MIT licensed, see LICENSE. Two model architectures are vendored so local inference works without pulling their full training stacks; both are Apache-2.0 and keep their own licence and attribution alongside the code:
| Component | Upstream | Licence |
|---|---|---|
pictograph.inference._rfdetr |
RF-DETR (Roboflow) | Apache-2.0 · NOTICE |
pictograph.inference._yolox |
YOLOX (Megvii) | Apache-2.0 · NOTICE |
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pictograph-1.69.67.tar.gz.
File metadata
- Download URL: pictograph-1.69.67.tar.gz
- Upload date:
- Size: 997.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fe37558e3251fe4d0f50294455edde9d643c7e121e0050059db5038ee2c11067
|
|
| MD5 |
d1367682fb1856465d27b51e76fba761
|
|
| BLAKE2b-256 |
3f939448ee552d9180ec5b92fd8c5e5f3a793506baef432eed34b72d9006c3c2
|
File details
Details for the file pictograph-1.69.67-py3-none-any.whl.
File metadata
- Download URL: pictograph-1.69.67-py3-none-any.whl
- Upload date:
- Size: 733.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bd793c434e2ff2f12ae3004259077100587c7081157a0510e9d4a2443c4ba5e5
|
|
| MD5 |
beed7ab25b5c5d8d7ab98ad702f98db7
|
|
| BLAKE2b-256 |
b875c7f73cc720094a171d5a663d85fb9f09aef10d12104639e3cf9d0043a28d
|
