Directories

A dataset’s images sit in directories: a label on each image, not a storage location, so moving images is instant. A directory is addressed by its path, which REST puts in the URL (/train/cars is .../directories/road-signs/train/cars).

list

The dataset’s directories, or only those directly inside parent.

Source: Directories.list

directories = client.directories.list(
    dataset="road-signs",
    parent="",
)
for d in directories:
    print(d.full_path, d.image_count)

pictograph directories list road-signs --parent ""

curl -s "https://api.pictograph.io/api/v1/developer/directories/road-signs?parent=" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns Sequence[Directory]

class Directory(BaseModel):
    """A single virtual directory in a dataset."""
    id: str
    dataset_id: str
    organization_id: str | None = None
    name: str
    parent_directory_id: str | None = None
    full_path: str
    image_count: int = 0
    nested_image_count: int = 0
    created_by: str | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

tree

The whole tree in one request, each node with its children.

Source: Directories.tree

tree = client.directories.tree(dataset="road-signs")
for node in tree:
    print(node.name, len(node.children))

pictograph directories tree road-signs

curl -s "https://api.pictograph.io/api/v1/developer/directories/road-signs/tree" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns Sequence[DirectoryTreeNode]

class DirectoryTreeNode(BaseModel):
    """A node in the hierarchical directory tree (children nested recursively)."""
    id: str
    name: str
    full_path: str
    image_count: int = 0
    nested_image_count: int = 0
    children: list[DirectoryTreeNode] = []

stats

Counts for one directory, its subdirectories included by default.

Source: Directories.stats

stats = client.directories.stats(
    dataset="road-signs",
    directory="/train/cars",
    include_subdirectories=True,
)
print(stats.total_images, stats.total_directories, stats.total_size_bytes)

pictograph directories stats road-signs /train/cars

curl -s "https://api.pictograph.io/api/v1/developer/directories/road-signs/train/cars/stats?include_subdirectories=true" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns DirectoryStats

class DirectoryStats(BaseModel):
    """Aggregate image statistics for a directory (and, by default, its subdirectories)."""
    total_directories: int
    total_images: int
    total_size_bytes: int
    directories_by_status: dict[str, int] = {}

create

Create a directory and any missing parents; an existing directory is returned as is. Needs a member key.

Source: Directories.create

directory = client.directories.create(
    dataset="road-signs",
    directory="/train/positive",
)
print(directory.id, directory.full_path)

pictograph directories create road-signs /train/positive

curl -s -X POST "https://api.pictograph.io/api/v1/developer/directories/" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" -H "Content-Type: application/json" \
  -d '{"dataset": "road-signs", "directory": "/train/positive"}'

Returns Directory

class Directory(BaseModel):
    """A single virtual directory in a dataset."""
    id: str
    dataset_id: str
    organization_id: str | None = None
    name: str
    parent_directory_id: str | None = None
    full_path: str
    image_count: int = 0
    nested_image_count: int = 0
    created_by: str | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

rename

Rename a directory; everything inside moves with it. Needs a member key.

Source: Directories.rename

directory = client.directories.rename(
    dataset="road-signs",
    directory="/train/cars",
    new_name="negatives",
)

pictograph directories rename road-signs /train/cars negatives

curl -s -X PATCH "https://api.pictograph.io/api/v1/developer/directories/road-signs/train/cars/rename" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY" -H "Content-Type: application/json" \
  -d '{"new_name": "negatives"}'

Returns Directory

class Directory(BaseModel):
    """A single virtual directory in a dataset."""
    id: str
    dataset_id: str
    organization_id: str | None = None
    name: str
    parent_directory_id: str | None = None
    full_path: str
    image_count: int = 0
    nested_image_count: int = 0
    created_by: str | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None

delete

Delete an empty directory. cascade=True first moves its images to its parent. Needs an admin key.

Source: Directories.delete

client.directories.delete(
    dataset="road-signs",
    directory="/train/cars",
    cascade=True,
)

pictograph directories delete road-signs /train/cars --cascade --yes

curl -s -X DELETE "https://api.pictograph.io/api/v1/developer/directories/road-signs/train/cars?cascade=true" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns None

Common errors