Skip to content
Tutorials5 min read

Image Classification with Potato

Set up image classification in Potato by displaying images with instance_display and collecting labels with radio and multiselect schemes, including quality checks.

Potato Team

Sooner or later most computer vision projects need a pile of labeled images, and someone has to do the labeling. Whether you're sorting product photos, screening content, or classifying medical scans, Potato handles the interface so you can focus on the labels. This tutorial covers the common setups: single-label and multi-label classification, nested category structures, and the quality checks that keep image tasks honest.

Showing the image, then asking the question

Classification and drawing are different jobs in Potato, and mixing them up is the usual first mistake. instance_display puts the picture on screen. annotation_schemes asks the question. The image_annotation type is for drawing boxes and masks on an image, so a classification task does not use it at all.

yaml
annotation_task_name: "Product Image Classification"
task_dir: "."
 
data_files:
  - data/products.json
 
item_properties:
  id_key: product_id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      label: "Product image"
      display_options:
        max_width: 600
        zoomable: true
 
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "What type of product is shown?"
    labels:
      - Electronics
      - Clothing
      - Home & Garden
      - Sports & Outdoors
      - Books & Media
      - Other
    sequential_key_binding: true
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl

sequential_key_binding gives the six labels the keys 1 through 6. On a task that is one glance and one click, the keyboard is most of the throughput.

The interface shows the image with the category labels beneath it:

Image classification interface with category labels and keyboard shortcutsThe image annotation interface showing a product image with classification labels and keyboard shortcuts

Data format

Create data/products.json:

json
{"product_id": "P001", "image_url": "/images/products/laptop.jpg"}
{"product_id": "P002", "image_url": "/images/products/tshirt.jpg"}
{"product_id": "P003", "image_url": "/images/products/garden_tools.jpg"}
{"product_id": "P004", "image_url": "https://example.com/images/basketball.jpg"}

Images can be local paths under the task directory or absolute URLs. text_key points at the field holding the path, which is the field Potato hands to the display.

Multi-label classification

Where an image belongs to several categories at once, use multiselect:

yaml
annotation_schemes:
  - annotation_type: multiselect
    name: attributes
    description: "Select all attributes that apply to this image"
    labels:
      - Contains people
      - Outdoor scene
      - Indoor scene
      - Contains text
      - Product photo
      - Lifestyle photo
      - Close-up shot
      - Wide angle

Nested categories

Potato has no nested label type for radio buttons, so a two-level taxonomy is two schemes. Every scheme needs its own labels, and a subcategory list has to cover every parent:

yaml
annotation_schemes:
  - annotation_type: radio
    name: main_category
    description: "Primary category"
    labels:
      - Apparel
      - Electronics
      - Home
 
  - annotation_type: radio
    name: subcategory
    description: "Subcategory within the primary category"
    labels:
      - Tops
      - Bottoms
      - Footwear
      - Phones & Tablets
      - Computers
      - Audio
      - Furniture
      - Kitchen
      - Decor

Where the second list would get long, hierarchical_multiselect collapses it into one widget instead of two schemes.

Quality checks alongside classification

yaml
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Product category"
    labels: [Electronics, Clothing, Home, Other]
 
  - annotation_type: radio
    name: image_quality
    description: "Is this image suitable for the product catalog?"
    labels:
      - name: Approved
        tooltip: "Clear, well-lit, product is visible"
      - name: Needs review
        tooltip: "Minor issues but potentially usable"
      - name: Rejected
        tooltip: "Poor quality, wrong product, or inappropriate"
 
  - annotation_type: multiselect
    name: quality_issues
    description: "If not approved, what issues are present?"
    labels:
      - Blurry or out of focus
      - Poor lighting
      - Wrong product shown
      - Watermark or text overlay
      - Inappropriate content
      - Multiple products in frame

The per-label guidance goes in tooltip, which is the key labels read. Writing it as description: on a label puts the text nowhere the annotator can see it.

Complete example

yaml
annotation_task_name: "E-commerce Image Classification"
task_dir: "."
 
data_files:
  - data/images.json
 
item_properties:
  id_key: sku
  text_key: image_path
 
instance_display:
  fields:
    - key: image_path
      type: image
      label: "Product image"
      display_options:
        max_width: 700
        zoomable: true
 
annotation_schemes:
  - annotation_type: radio
    name: primary_category
    description: "Select the main product category"
    labels:
      - Electronics
      - Clothing & Accessories
      - Home & Living
      - Beauty & Personal Care
      - Sports & Fitness
      - Toys & Games
      - Other
    sequential_key_binding: true
 
  - annotation_type: multiselect
    name: image_attributes
    description: "Select all that apply"
    labels:
      - White background
      - Lifestyle shot
      - Multiple angles
      - Model wearing or using
      - Size reference included
      - Brand visible
    label_requirement:
      required: false
 
  - annotation_type: radio
    name: listing_ready
    description: "Is this image ready for the product listing?"
    labels:
      - Ready to publish
      - Needs editing
      - Reshoot required
    label_requirement:
      required: true
 
annotation_instructions: |
  ## Image Classification Guidelines
 
  ### Category selection
  Choose the most specific category that fits the product.
 
  ### Image quality
  - Ready to publish: clear, professional, meets standards
  - Needs editing: good photo that needs cropping or color correction
  - Reshoot required: fundamentally unsuitable
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl

Tips for image annotation

Color and brightness vary between monitors, so for anything where that matters, make sure annotators are on reasonably calibrated displays. Put example images in your guidelines rather than describing categories in words; one picture settles more arguments than a paragraph. Write down what to do with the ambiguous images, because there will be ambiguous images. And every so often, have the team label the same batch and compare, so drift gets caught early.

For implementation details, see the image annotation documentation.

Next steps

See complete image annotation documentation at Image Annotation.