Uploading Files With Attributes

Learn how to upload files with attributes using the SDK

This page will show you basic examples for uploading files with instances and attributes (both global attributes and instance attributes).

SDK Example

Let's take a simple example for uploading an image with bounding boxes:

def upload_image_with_3_boxes():
  signed_url = "https://storage.googleapis.com/diffgram_public/example_data/000000001323.jpg"

  instance_list = []
  def create_box_instance(
          sequence_number: int = None,
          name: str = None):
      return {
          "name": name,
          "type": "box",
          "x_max": random.randint(180, 220),
          "x_min": random.randint(100, 120),
          "y_max": random.randint(230, 260),
          "y_min": random.randint(130, 160)
      }

  for i in range(3):
    instance_list.append(
      mock_box_from_external_format(name = "my_label_name"))

    result = project.file.from_url(
      signed_url,
      media_type = "image",
      instance_list = instance_list
    )
    print(result)

In this example we upload a single image URL with 3 bounding boxes. The boxes have no attributes yet. And the file has not global attributes either. Let's see how to add an instance attribute first

Instance Level Attributes

To add attributes to an instance, you just have to specify the attribute_groups key on the instance object. This is an object with the format <attribute_group_id>:<attribute_group_selected_value_object>.

Let's see at each of these values in detail:

attribute_group_id: This value is the attribute template group ID you want to fill. In order to get the attribute group value you want to use, you can call the function project.get_attributes(schema_id)
attribute_group_selected_value_object: This is an object indicating the selected value or the value inputted from the annotator. It is composed of the following:

Radio Buttons

{
display_name: "My selected option" # The display name of the selected attribute option
id: 2 #The ID of the selected attribute option
name: "My selected option" # The internal name of the selected attribute option.,
  
}

You can find the available options to select on the attribute_template_list key of each attribute group when calling the project.get_attributes(schema_id) function.

Tree View

{
    5: {name: "my option", selected: true} 
}

In the tree view case, we have a nested object. The key of this object is the id of the option (in this case the "myoption" attribute option has id 5). And the value of this object is the name of the option along with a selected attribute.

Putting this together on the instance it will look something like this (Assuming the radio button attribute has id=1 and tree view attribute has id=2.

def create_box_instance(
          sequence_number: int = None,
          name: str = None):
      return {
          "name": name,
          "type": "box",
          "x_max": random.randint(180, 220),
          "x_min": random.randint(100, 120),
          "y_max": random.randint(230, 260),
          "y_min": random.randint(130, 160),
          "attribute_groups": {1: {
                                                    "display_name": "My selected option" # The display name of the selected attribute option
                                                                "id": 2 #The ID of the selected attribute option
                                                    "name": "My selected option" # The internal name of the selected attribute option.
                                                        },
                               2: {
                                5: {"name": "my option", "selected": true} 
                               }
         }
      }

Uploading Files With Global Attributes

Global attributes work in a similar way as instance attributes, the only difference is that you have to declare a special type of instance called global, this instance does not need a label name so you can leave that field in blank, same for the x and y values.

def create_global_instance(
          sequence_number: int = None,
          name: str = None):
      return {
          "type": "global",
          "attribute_groups": {3: {
                                                    "display_name": "My selected Global Attribute",
                                                              "id": 10,
                                                    "name": "My selected Global Attribute"
                                                        }
         }
      }

In the above example the global attribute is id=3 and the selected option (radio button) is 10

Full Example with a Global Attribute

import random
from diffgram import Project

project = Project(
    project_string_id = "my_project",
    client_id = "my_client_id",
    client_secret = "my_secret",
)

print(project.client_id)

dataset = project.directory.get('Default')


def mock_box_from_external_format(
        sequence_number: int = None,
        name: str = None):
    return {
        "name": name,
        "number": sequence_number,
        "type": "box",
        "x_max": random.randint(180, 220),
        "x_min": random.randint(100, 120),
        "y_max": random.randint(230, 260),
        "y_min": random.randint(130, 160)
    }


def create_global_attribute():
    return {
        "name": None,
        "number": None,
        "type": "global",
        'attribute_groups': {
            1: {
                'display_name': 'R',
                'id': 1,
                'name': 1
            }
        }
    }


def upload_image_with_instances(project):
    signed_url = "https://storage.googleapis.com/diffgram_public/example_data/000000001323.jpg"

    instance_list = []

    for i in range(3):
        instance_list.append(
            mock_box_from_external_format(name = "my_label"))
    global_attr = create_global_attribute()

    instance_list.append(global_attr)
    result = project.file.from_url(
        signed_url,
        media_type = "image",
        instance_list = instance_list
    )
    print(result)


upload_image_with_instances(project)