Work with Images

Image is an object recognized by ApertureDB and the query language allows you to directly add, find, update, and delete images.

Connect to ApertureDB

Option A: ApertureDB Cloud (recommended)
Sign up for a free 30-day trial. Get your key from Connect > Generate API Key, add it to a .env file in this directory:

APERTUREDB_KEY=your_key_here

Option B: Community Edition (local Docker)
Run this in a terminal before starting the notebook:

docker run -d --name aperturedb \
  -p 55555:55555 -e ADB_MASTER_KEY=admin -e ADB_FORCE_SSL=false \
  aperturedata/aperturedb-community

%pip install --upgrade --quiet aperturedb python-dotenv

# Option A: ApertureDB Cloud
from dotenv import load_dotenv
load_dotenv()  # loads APERTUREDB_KEY from .env into the environment

True

# Option B: Community Edition (local Docker)
# !adb config create localdb --active \
#     --host localhost --port 55555 \
#     --username admin --password admin \
#     --no-use-ssl --no-interactive

from aperturedb.CommonLibrary import create_connector

client = create_connector()
response, _ = client.query([{"GetStatus": {}}])
client.print_last_response()

[
    {
        "GetStatus": {
            "info": "OK",
            "status": 0,
            "system": "ApertureDB",
            "version": "0.19.6"
        }
    }
]

Create or Add an Image of a Dish to ApertureDB

Let's say we want to add some pictures of food we prepared. One way to introduce new images in the database is through our query language

For bulk additions, we recommend using the Python SDK loaders

# Download the sample file needed in this example
! mkdir -p data; cd data; wget https://github.com/aperture-data/Cookbook/blob/e333f6c59070b9165033d9ddd5af852a6b9624ba/notebooks/simple/data/focaccia_brittany.jpg; cd -

query = [{
    "AddImage": {
        # Notice the missing "class" property since we already know its an Image (represented as _Image in ApertureDB)
        "properties": {
            "name": "Focaccia",
            "id": 35,
            "contributor": "Vishakha",
            "category": "starter",
            "cuisine": "Italian",
            "location": "Brittany",
            "caption": "fresh made focaccia with herbs from the garden"
        },
        "if_not_found": {                  # avoid adding twice
            "id": ["==", 35]
        }
    }
}]

# Read the image data as a binary blob
fd = open("data/focaccia_brittany.jpg", 'rb')
image_arr = [ fd.read() ]
fd.close()

response, blobs = client.query(query, image_arr)

client.print_last_response()

[
    {
        "AddImage": {
            "status": 0
        }
    }
]

Query image by its metadata attributes

Verify this Image was added to the database and read all the property values

from aperturedb import NotebookHelpers as nh   # Our helper package for image displays and other utilities

query = [{
    "FindImage": {
        "constraints": {
            "name": ["==", "Focaccia"],
            "location": [">", "A"] 
        },
        "blobs": True,                          # This is set to False by default
        "results": {
            "all_properties": True
        }
    }
}]

response, blobs = client.query(query)

client.print_last_response()
nh.display(blobs)

[
    {
        "FindImage": {
            "blobs_start": 0,
            "entities": [
                {
                    "_blob_index": 0,
                    "_uniqueid": "7.246632.224360",
                    "caption": "fresh made focaccia with herbs from the garden",
                    "category": "starter",
                    "contributor": "Vishakha",
                    "cuisine": "Italian",
                    "id": 35,
                    "location": "Brittany",
                    "name": "Focaccia"
                }
            ],
            "returned": 1,
            "status": 0
        }
    }
]

Update properties of the image already in ApertureDB

Use UpdateImage if any of the attributes need a new value or your application now needs a new attribute in existing images

query = [{
    "UpdateImage": {
        "properties": {
            "recipe_url": "https://www.allrecipes.com/recipe/23451/fantastic-focaccia-bread/"     # property will get added if missing or the value will be updated
        },
        "constraints": {
            "name": ["==", "Focaccia"]
        },
    }
}]

response, blobs = client.query(query)

client.print_last_response()

[
    {
        "UpdateImage": {
            "count": 1,
            "status": 0
        }
    }
]

query = [{
    "FindImage": {
        "constraints": {
            "name": ["==", "Focaccia"]
        },
        "results": {
            "all_properties": True
        }
    }
}]

response, blobs = client.query(query)

client.print_last_response()

[
    {
        "FindImage": {
            "entities": [
                {
                    "_uniqueid": "7.246632.224360",
                    "caption": "fresh made focaccia with herbs from the garden",
                    "category": "starter",
                    "contributor": "Vishakha",
                    "cuisine": "Italian",
                    "id": 35,
                    "location": "Brittany",
                    "name": "Focaccia",
                    "recipe_url": "https://www.allrecipes.com/recipe/23451/fantastic-focaccia-bread/"
                }
            ],
            "returned": 1,
            "status": 0
        }
    }
]

Delete the image we no longer need

query = [{
    "DeleteImage": {
        "constraints": {
            "name": ["==", "Focaccia"]
        }
    }
}]

response, blobs = client.query(query)

client.print_last_response()

[
    {
        "DeleteImage": {
            "count": 1,
            "status": 0
        }
    }
]

Verify deletion

We can verify that the image is not longer in the database.

query = [{
    "FindImage": {
        "constraints": {
            "name": ["==", "Focaccia"]     # if this matches multiple images, they will all be deleted
        },
        "results": {
            "all_properties": True
        }
    }
}]

response, blobs = client.query(query)

client.print_last_response()

[
    {
        "FindImage": {
            "returned": 0,
            "status": 0
        }
    }
]

What's next?

• Bulk load images
• Add embeddings or regions of interest to ApertureDB