name: storage-label-images
version: 0.1.7
specVersion: v1beta

displayName: Label Images with Cloud Vision AI
description:
  Extracts labels from images and saves to Firestore using Cloud Vision API.

license: Apache-2.0 # The license you want for the extension
sourceUrl: https://github.com/GoogleCloudPlatform/firebase-extensions/tree/main/storage-label-images
releaseNotesUrl: https://github.com/GoogleCloudPlatform/firebase-extensions/tree/main/storage-label-images/CHANGELOG.md

icon: icon.png

tags:
  [
    ai,
    videos,
    cloud-vision,
    image-recognition,
    image-classification,
    google-ai,
    cloud-vision-api,
  ]

author:
  authorName: Google Cloud
  url: https://cloud.google.com/

billingRequired: true

apis:
  - apiName: vision.googleapis.com
    reason: Powers all Vision tasks performed by the extension.

resources:
  - name: labelImage
    type: firebaseextensions.v1beta.function
    description:
      Listens to incoming Storage documents, executes image labeling on them and
      writes labels back to Storage into a preconfigured location.
    properties:
      location: ${param:LOCATION}
      availableMemoryMb: 1024
      eventTrigger:
        eventType: google.storage.object.finalize
        resource: projects/_/buckets/${param:IMG_BUCKET}
      runtime: nodejs20

params:
  - param: LOCATION
    label: Cloud Functions location
    description: >-
      Where do you want to deploy the functions created for this extension? You
      usually want a location close to your database. Realtime Database
      instances are located in `us-central1`. For help selecting a location,
      refer to the [location selection
      guide](https://firebase.google.com/docs/functions/locations).
    type: select
    options:
      - label: Iowa (us-central1)
        value: us-central1
      - label: South Carolina (us-east1)
        value: us-east1
      - label: Northern Virginia (us-east4)
        value: us-east4
      - label: Belgium (europe-west1)
        value: europe-west1
      - label: London (europe-west2)
        value: europe-west2
      - label: Frankfurt (europe-west3)
        value: europe-west3
      - label: Hong Kong (asia-east2)
        value: asia-east2
      - label: Tokyo (asia-northeast1)
        value: asia-northeast1
    default: us-central1
    required: true
    immutable: true

  - param: IMG_BUCKET
    label: Cloud Storage bucket for images
    description: >
      To which Cloud Storage bucket will you upload images on which you want to
      perform labelling?
    type: string
    example: my-project-12345.appspot.com
    validationRegex: ^([0-9a-z_.-]*)$
    validationErrorMessage: Invalid storage bucket
    default: ${STORAGE_BUCKET}
    required: true

  - param: INCLUDE_PATH_LIST
    label: Paths that contain images you want to label
    description: >
      Restrict storage-image-labeling to only label images in specific locations
      in your Storage bucket by  supplying a comma-separated list of absolute
      paths. For example, specifying the paths
      `/users/pictures,/restaurants/menuItems` will label any images found in
      any subdirectories of `/users/pictures` and `/restaurants/menuItems`.

      You may also use wildcard notation for directories in the path. For
      example, `/users/*/pictures` would include any images in any
      subdirectories of `/users/foo/pictures` as well as any images in
      subdirectories of `/users/bar/pictures`, but also any images in
      subdirectories of `/users/any/level/of/subdirectories/pictures`. 

      If you prefer not to explicitly exclude any directories of your Storage
      bucket, leave this field empty.
    type: string
    example: '/users/avatars,/design/pictures'
    validationRegex: ^(\/[^\s\/\,]+)+(\,(\/[^\s\/\,]+)+)*$
    validationErrorMessage:
      Invalid paths, must be a comma-separated list of absolute path values.
    required: false

  - param: EXCLUDE_PATH_LIST
    label: List of absolute paths not included for labelled images
    description: >
      Ensure storage-image-labeling does *not* label images in _specific
      locations_ in your Storage bucket by  supplying a comma-separated list of
      absolute paths. For example, to *exclude* the images  stored in the
      `/foo/alpha` and its subdirectories and `/bar/beta` and its
      subdirectories, specify the paths `/foo/alpha,/bar/beta`.

      You may also use wildcard notation for directories in the path. For
      example, `/users/*/pictures` would exclude any images in any
      subdirectories of `/users/foo/pictures` as well as any images in
      subdirectories of `/users/bar/pictures`, but also any images in
      subdirectories of `/users/any/level/of/subdirectories/pictures`.

      If you prefer to label every image uploaded to your Storage bucket,  leave
      this field empty.
    type: string
    example: '/users/avatars/thumbs,/design/pictures/thumbs'
    validationRegex: ^(\/[^\s\/\,]+)+(\,(\/[^\s\/\,]+)+)*$
    validationErrorMessage:
      Invalid paths, must be a comma-separated list of absolute path values.
    required: false

  - param: COLLECTION_PATH
    label: Collection path
    description: >
      What is the path to the collection where labels will be written to?
    example: imageLabels
    validationRegex: '^[^/]+(/[^/]+/[^/]+)*$'
    validationErrorMessage: Must be a valid Cloud Firestore Collection
    default: imageLabels
    required: true

  - param: LABEL_MODE
    label: Amount of label information to write to firestore.
    description: >
      How much label information should be written to firestore? Do you want
      just the label descriptions written to firestore,  or the full label
      annotation? Select \"basic\" for the former, \"full\" for the later.
    type: select
    options:
      - label: Basic
        value: basic
      - label: Full
        value: full
    default: basic
    required: true

roles:
  - role: storage.objectAdmin
    reason: Allows the extension to write to your Cloud Storage.
  - role: datastore.user
    reason: Allows the extension to write to your Firestore Database instance.
