Image Operations

This section covers all read operations available for images in the Rosepetal API.

Overview

Images are the core data elements in the Rosepetal system. They contain visual data along with metadata such as annotations, tags, and classification information. The API provides endpoints to retrieve, analyze, and download images.

Image Structure

Each image object contains the following key properties:

Field	Type	Description
uri	string	Google Cloud Storage URI
name	string	Original filename
dataset	reference	Associated dataset reference
tag	reference	Primary classification tag
tags	array	Additional annotation tags
tagsContained	array	References to all contained tags
set	string	Training set assignment
imageData	buffer	Thumbnail image data (WebP, 300px)
date	number	Upload timestamp
monitor	reference	Source monitor reference

Endpoints

Delete Image

Remove an image from storage and database.

GET /image/delete/image/{encoded_uri}

Parameters:

Parameter	Type	Description
encoded_uri	string	Image URI with / replaced by --

Example Request:

GET /image/delete/image/upload--monitor-1--20240115.png

Response:

{
  "error": false,
  "status": "success"
}

Error Response:

{
  "error": true,
  "status": "Permission denied or file not found"
}

Object Detection

Analyze an image for objects using Google Cloud Vision API.

GET /image/detect/image/{encoded_uri}

Parameters:

Parameter	Type	Description
encoded_uri	string	Image URI with / replaced by --

Example Request:

GET /image/detect/image/upload--monitor-1--20240115.png

Response:

{
  "result": [
    {
      "bbox": [0.1, 0.2, 0.3, 0.4],
      "class": "Person",
      "score": 0.95
    },
    {
      "bbox": [0.5, 0.6, 0.2, 0.3],
      "class": "Vehicle",
      "score": 0.87
    }
  ]
}

Bounding Box Format:

• bbox[0]: X coordinate of top-left corner (normalized 0-1)
• bbox[1]: Y coordinate of top-left corner (normalized 0-1)
• bbox[2]: Width (normalized 0-1)
• bbox[3]: Height (normalized 0-1)

Get Image as Base64

Retrieve an image as a base64-encoded data URI.

GET /image/getb64/image/{encoded_uri}

Parameters:

Parameter	Type	Description
encoded_uri	string	Image URI with / replaced by --

Example Request:

GET /image/getb64/image/upload--monitor-1--20240115.png

Response:

{
  "result": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Error Response:

{
  "error": true,
  "uri": "upload/monitor-1/20240115.png",
  "status": "File not found"
}

Image Sets

Images are organized into training sets for machine learning:

Set	Description	Typical Usage
TRAIN	Training data	60-80% of dataset
TEST	Testing data	10-20% of dataset
VALIDATION	Validation data	10-20% of dataset
PREDETERMINED	Default assignment	Before set splitting
REVIEW	Requires manual review	Quality control

Annotation Structure

Tags Array

Each image can have multiple annotations in the tags array:

{
  "tags": [
    {
      "type": "rect",
      "tag": "dataset/123/tag/defect",
      "x": 0.1,
      "y": 0.2,
      "w": 0.3,
      "h": 0.4,
      "labeled": "manual"
    }
  ]
}

Tag Properties:

Field	Type	Description
type	string	Annotation type (rect, mask, point)
tag	reference	Tag classification reference
x, y	number	Top-left coordinates (normalized 0-1)
w, h	number	Width and height (normalized 0-1)
labeled	string	Source of annotation (manual, inference)

Masks (Segmentation)

For segmentation datasets, images may contain mask information:

{
  "masks": [
    {
      "tag": "dataset/123/tag/defect-type",
      "uri": "gs://bucket/masks/mask_123.png"
    }
  ]
}

Image Metadata

Upload Information

Field	Type	Description
date	number	Unix timestamp of upload
monitor	reference	Source monitor/camera
session	string	Recording session ID
createdDate	timestamp	Firestore creation time
updatedAt	timestamp	Last modification time

Processing Information

Field	Type	Description
imageData	buffer	Thumbnail preview (WebP)
originalFormat	string	Original file format
width	number	Image width in pixels
height	number	Image height in pixels

URI Encoding

When working with image URIs in API calls, replace forward slashes with double dashes:

Original URI:

gs://project/upload/monitor/image.png

Encoded for API:

upload--monitor--image.png

Error Handling

Common Error Responses

Image Not Found

{
  "error": true,
  "status": "File not found"
}

Invalid URI Format

{
  "error": "No defined image gsuri"
}

Processing Error

{
  "error": true,
  "status": "Permission denied"
}

Detection API Error

{
  "error": "Vision API quota exceeded"
}

Query Examples

Basic Image Retrieval

// Get image as base64
const response = await fetch('/image/getb64/image/upload--camera-1--image.png');
const data = await response.json();
console.log(data.result); // data:image/png;base64,...

Object Detection Analysis

// Detect objects in image
const response = await fetch('/image/detect/image/upload--camera-1--image.png');
const data = await response.json();
data.result.forEach(obj => {
  console.log(`${obj.class}: ${obj.score}`);
  console.log(`Bbox: ${obj.bbox}`);
});

Safe Image Deletion

// Delete image with error handling
const response = await fetch('/image/delete/image/upload--old-image.png');
const data = await response.json();
if (data.error) {
  console.error('Delete failed:', data.status);
} else {
  console.log('Image deleted successfully');
}