detection

package
v1.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 20, 2025 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrProviderNotConfigured indicates missing credentials or configuration
	ErrProviderNotConfigured = errors.New("provider not configured or credentials missing")

	// ErrInvalidFeature indicates an unsupported feature was requested
	ErrInvalidFeature = errors.New("invalid or unsupported detection feature")

	// ErrImageTooLarge indicates the image exceeds provider size limits
	ErrImageTooLarge = errors.New("image exceeds provider size limits")

	// ErrUnsupportedFormat indicates the image format is not supported
	ErrUnsupportedFormat = errors.New("image format not supported by provider")

	// ErrAPIError indicates a generic API error
	ErrAPIError = errors.New("provider API error")

	// ErrRateLimit indicates API rate limit was exceeded
	ErrRateLimit = errors.New("provider API rate limit exceeded")

	// ErrInvalidAPIKey indicates authentication failed
	ErrInvalidAPIKey = errors.New("invalid API key or credentials")

	// ErrNetworkError indicates a network connectivity issue
	ErrNetworkError = errors.New("network error communicating with provider")

	// ErrInvalidImage indicates the image data is invalid
	ErrInvalidImage = errors.New("invalid image data")

	// ErrContextCanceled indicates the context was canceled
	ErrContextCanceled = errors.New("detection canceled by context")
)

Common detection errors

Functions

func AssertBox 

func AssertBox(t *testing.T, box *Box)

AssertBox validates a Box structure

func AssertContextDeadline 

func AssertContextDeadline(t *testing.T, fn func(context.Context) error, timeout time.Duration)

AssertContextDeadline checks that an operation respects context deadlines

func AssertDetectionResult 

func AssertDetectionResult(t *testing.T, result *DetectionResult)

AssertDetectionResult validates a DetectionResult structure

func AssertEqual 

func AssertEqual(t *testing.T, got, want interface{}, msg string)

AssertEqual checks if two values are equal

func AssertError 

func AssertError(t *testing.T, err error, msg string)

AssertError is a helper to check for an error

func AssertFace 

func AssertFace(t *testing.T, face Face)

AssertFace validates a Face structure

func AssertLabel 

func AssertLabel(t *testing.T, label Label)

AssertLabel validates a Label structure

func AssertNoError 

func AssertNoError(t *testing.T, err error, msg string)

AssertNoError is a helper to check for no error

func AssertNotNil 

func AssertNotNil(t *testing.T, value interface{}, msg string)

AssertNotNil checks if a value is not nil

func AssertTextBlock 

func AssertTextBlock(t *testing.T, text TextBlock)

AssertTextBlock validates a TextBlock structure

func AssertValidConfidence 

func AssertValidConfidence(t *testing.T, confidence float32, name string)

AssertValidConfidence checks if a confidence score is in valid range

func CreateTestImage 

func CreateTestImage(width, height int, c color.NRGBA) *image.NRGBA

CreateTestImage creates a solid color test image

func CreateTestImageWithPattern 

func CreateTestImageWithPattern(width, height int) *image.NRGBA

CreateTestImageWithPattern creates a test image with a pattern

func CreateTestImageWithText 

func CreateTestImageWithText(width, height int) *image.NRGBA

CreateTestImageWithText creates a simple image with text-like patterns

func GetDefaultConfidence 

func GetDefaultConfidence() float32

GetDefaultConfidence returns the default confidence threshold

func GetDefaultProvider 

func GetDefaultProvider() string

GetDefaultProvider returns the default provider name

func GetTimeout 

func GetTimeout() int

GetTimeout returns the API request timeout

func IsInvalidAPIKey 

func IsInvalidAPIKey(err error) bool

IsInvalidAPIKey checks if error is ErrInvalidAPIKey

func IsNotConfigured 

func IsNotConfigured(err error) bool

IsNotConfigured checks if error is ErrProviderNotConfigured

func IsRateLimit 

func IsRateLimit(err error) bool

IsRateLimit checks if error is ErrRateLimit

func LoadFixtureResponse 

func LoadFixtureResponse(t *testing.T, filename string) []byte

LoadFixtureResponse loads a JSON fixture from testdata/responses

func ResolveProviderAlias 

func ResolveProviderAlias(name string) string

ResolveProviderAlias resolves provider name aliases "google" -> "gemini" (Google's AI Studio API)

func SetDefaultConfidence 

func SetDefaultConfidence(confidence float32)

SetDefaultConfidence sets the default confidence threshold

func SetDefaultProvider 

func SetDefaultProvider(provider string)

SetDefaultProvider sets the default provider name

func SetTimeout 

func SetTimeout(timeout int)

SetTimeout sets the API request timeout

func SkipIfNoCredentials 

func SkipIfNoCredentials(t *testing.T, provider string)

SkipIfNoCredentials skips a test if the specified provider credentials are not available

Types

type AWSProvider 

type AWSProvider struct {
	// contains filtered or unexported fields
}

AWSProvider implements the Provider interface for AWS Rekognition

func NewAWSProvider 

func NewAWSProvider() (*AWSProvider, error)

NewAWSProvider creates a new AWS Rekognition provider instance It uses the default AWS credential chain which checks in order: 1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) 2. AWS credentials file (~/.aws/credentials) 3. AWS config file (~/.aws/config) 4. IAM roles for Amazon EC2, ECS, or Lambda

func (*AWSProvider) Close 

func (a *AWSProvider) Close() error

Close closes the AWS client (no-op for AWS SDK v2)

func (*AWSProvider) Detect 

func (a *AWSProvider) Detect(ctx context.Context, img *image.NRGBA, opts *DetectOptions) (*DetectionResult, error)

Detect performs object detection using AWS Rekognition

func (*AWSProvider) IsConfigured 

func (a *AWSProvider) IsConfigured() bool

IsConfigured checks if the provider is properly configured

func (*AWSProvider) Name 

func (a *AWSProvider) Name() string

Name returns the provider name

type BoundingBox 

type BoundingBox struct {
	Label      string  `json:"label"`      // Object label
	Confidence float32 `json:"confidence"` // Detection confidence
	Box        Box     `json:"box"`        // Bounding box coordinates
}

BoundingBox represents object location in the image

type Box 

type Box struct {
	X      float32 `json:"x"`      // X coordinate (top-left)
	Y      float32 `json:"y"`      // Y coordinate (top-left)
	Width  float32 `json:"width"`  // Box width
	Height float32 `json:"height"` // Box height
}

Box represents rectangular coordinates

type ColorInfo added in v1.1.1 

type ColorInfo struct {
	Name       string  `json:"name,omitempty"`       // Human-friendly color name
	Hex        string  `json:"hex,omitempty"`        // Hex value (e.g. #AABBCC)
	RGB        string  `json:"rgb,omitempty"`        // RGB tuple string
	Percentage float32 `json:"percentage,omitempty"` // Coverage percentage (0.0-100.0)
}

ColorInfo describes a dominant color detected in the image

type Config 

type Config struct {
	// DefaultProvider is the default detection provider
	DefaultProvider string

	// DefaultConfidence is the default minimum confidence threshold
	DefaultConfidence float32

	// MaxConcurrentRequests limits concurrent API requests
	MaxConcurrentRequests int

	// CacheResults enables result caching (future feature)
	CacheResults bool

	// Timeout specifies API request timeout in seconds
	Timeout int
	// contains filtered or unexported fields
}

Config holds global detection configuration

type DetectOptions 

type DetectOptions struct {
	// Features specifies what to detect (labels, text, faces, web, etc.)
	Features []Feature `json:"features,omitempty"`

	// MaxResults limits the number of labels to return
	MaxResults int `json:"max_results,omitempty"`

	// MinConfidence sets the minimum confidence threshold (0.0-1.0)
	MinConfidence float32 `json:"min_confidence,omitempty"`

	// CustomPrompt for Gemini/OpenAI to ask custom questions
	CustomPrompt string `json:"custom_prompt,omitempty"`

	// Language hint for text detection
	Language string `json:"language,omitempty"`

	// IncludeRawResponse includes raw API response in result
	IncludeRawResponse bool `json:"include_raw_response,omitempty"`
}

DetectOptions contains detection configuration options

func DefaultDetectOptions 

func DefaultDetectOptions() *DetectOptions

DefaultDetectOptions returns default detection options

type DetectionError 

type DetectionError struct {
	Provider string // Provider name
	Message  string // Error message
	Code     string // Provider-specific error code
	Err      error  // Underlying error
}

DetectionError wraps provider-specific errors

func NewDetectionError 

func NewDetectionError(provider, message string, err error) *DetectionError

NewDetectionError creates a new DetectionError

func (*DetectionError) Error 

func (e *DetectionError) Error() string

Error implements the error interface

func (*DetectionError) Unwrap 

func (e *DetectionError) Unwrap() error

Unwrap returns the underlying error

type DetectionResult 

type DetectionResult struct {
	Provider      string             `json:"provider"`                 // Provider name
	Labels        []Label            `json:"labels,omitempty"`         // Detected objects/labels
	Description   string             `json:"description,omitempty"`    // Natural language description
	Text          []TextBlock        `json:"text,omitempty"`           // OCR results
	Faces         []Face             `json:"faces,omitempty"`          // Face detection
	Web           *WebDetection      `json:"web,omitempty"`            // Web search results
	BoundingBoxes []BoundingBox      `json:"bounding_boxes,omitempty"` // Object locations
	Colors        []ColorInfo        `json:"colors,omitempty"`         // Dominant colors and palettes
	ImageQuality  *ImageQuality      `json:"image_quality,omitempty"`  // Brightness/contrast metrics
	Moderation    []ModerationLabel  `json:"moderation,omitempty"`     // Safe-search or moderation labels
	Properties    map[string]string  `json:"properties,omitempty"`     // Provider-specific data
	SafeSearch    *SafeSearchSummary `json:"safe_search,omitempty"`    // Provider-safe-search summary
	Confidence    float32            `json:"confidence"`               // Overall confidence 0.0-1.0
	Error         string             `json:"error,omitempty"`          // Error message if detection failed
	RawResponse   string             `json:"raw_response,omitempty"`   // Raw API response for debugging
	ProcessedAt   time.Time          `json:"processed_at"`             // When detection ran
}

DetectionResult contains all detection results from a provider

func CreateMockDetectionResult 

func CreateMockDetectionResult(provider string) *DetectionResult

CreateMockDetectionResult creates a mock DetectionResult for testing

type Face 

type Face struct {
	Confidence         float32    `json:"confidence"`                    // Detection confidence
	BoundingBox        *Box       `json:"bounding_box,omitempty"`        // Face location
	JoyLikelihood      string     `json:"joy_likelihood,omitempty"`      // Emotion: joy
	SorrowLikelihood   string     `json:"sorrow_likelihood,omitempty"`   // Emotion: sorrow
	AngerLikelihood    string     `json:"anger_likelihood,omitempty"`    // Emotion: anger
	SurpriseLikelihood string     `json:"surprise_likelihood,omitempty"` // Emotion: surprise
	Gender             string     `json:"gender,omitempty"`              // Male/Female
	AgeRange           string     `json:"age_range,omitempty"`           // Age range estimate
	Landmarks          []Landmark `json:"landmarks,omitempty"`           // Facial landmarks
}

Face represents a detected face

type Feature 

type Feature string

Feature represents a detection feature type 

const (
	// FeatureLabels detects objects and labels
	FeatureLabels Feature = "labels"

	// FeatureText performs OCR text detection
	FeatureText Feature = "text"

	// FeatureFaces detects faces and emotions
	FeatureFaces Feature = "faces"

	// FeatureWeb searches for similar images on the web (Google only)
	FeatureWeb Feature = "web"

	// FeatureDescription generates natural language descriptions
	FeatureDescription Feature = "description"

	// FeatureProperties extracts image properties (colors, etc.)
	FeatureProperties Feature = "properties"

	// FeatureObjects detects objects with bounding boxes
	FeatureObjects Feature = "objects"

	// FeatureLandmarks detects landmarks
	FeatureLandmarks Feature = "landmarks"

	// FeatureLogos detects logos
	FeatureLogos Feature = "logos"

	// FeatureSafeSearch detects adult/violent content
	FeatureSafeSearch Feature = "safesearch"
)

func ParseFeatures 

func ParseFeatures(s string) []Feature

ParseFeatures parses a comma-separated string into Feature slice

func (Feature) String 

func (f Feature) String() string

String returns the string representation of a Feature

type GeminiProvider 

type GeminiProvider struct {
	// contains filtered or unexported fields
}

GeminiProvider implements the Provider interface for Google Gemini API

func NewGeminiProvider 

func NewGeminiProvider() (*GeminiProvider, error)

NewGeminiProvider creates a new Gemini provider instance

func (*GeminiProvider) Close 

func (g *GeminiProvider) Close() error

Close closes the Gemini client (no-op as genai.Client doesn't require explicit closing)

func (*GeminiProvider) Detect 

func (g *GeminiProvider) Detect(ctx context.Context, img *image.NRGBA, opts *DetectOptions) (*DetectionResult, error)

Detect performs object detection using Gemini API

func (*GeminiProvider) IsConfigured 

func (g *GeminiProvider) IsConfigured() bool

IsConfigured checks if the provider is properly configured

func (*GeminiProvider) Name 

func (g *GeminiProvider) Name() string

Name returns the provider name

type ImageQuality added in v1.1.1 

type ImageQuality struct {
	Brightness           float32 `json:"brightness,omitempty"`
	Sharpness            float32 `json:"sharpness,omitempty"`
	Contrast             float32 `json:"contrast,omitempty"`
	ForegroundBrightness float32 `json:"foreground_brightness,omitempty"`
	ForegroundSharpness  float32 `json:"foreground_sharpness,omitempty"`
	ForegroundColor      string  `json:"foreground_color,omitempty"`
	BackgroundBrightness float32 `json:"background_brightness,omitempty"`
	BackgroundSharpness  float32 `json:"background_sharpness,omitempty"`
	BackgroundColor      string  `json:"background_color,omitempty"`
}

ImageQuality captures brightness/contrast metrics for the image (and segments)

type Label 

type Label struct {
	Name       string   `json:"name"`                 // Object/label name
	Confidence float32  `json:"confidence"`           // 0.0-1.0 confidence score
	Score      float32  `json:"score,omitempty"`      // Provider-specific score
	MID        string   `json:"mid,omitempty"`        // Machine ID (Google)
	Categories []string `json:"categories,omitempty"` // Category hierarchy
	TopicID    string   `json:"topic_id,omitempty"`   // Topic identifier
}

Label represents a detected object or label

type Landmark 

type Landmark struct {
	Type string  `json:"type"` // LEFT_EYE, RIGHT_EYE, NOSE_TIP, etc.
	X    float32 `json:"x"`
	Y    float32 `json:"y"`
	Z    float32 `json:"z,omitempty"`
}

Landmark represents a facial landmark point

type MockProvider 

type MockProvider struct {
	NameFunc         func() string
	IsConfiguredFunc func() bool
	DetectFunc       func(ctx context.Context, img *image.NRGBA, opts *DetectOptions) (*DetectionResult, error)
}

MockProvider is a mock implementation of the Provider interface for testing

func (*MockProvider) Detect 

func (m *MockProvider) Detect(ctx context.Context, img *image.NRGBA, opts *DetectOptions) (*DetectionResult, error)

Detect performs detection

func (*MockProvider) IsConfigured 

func (m *MockProvider) IsConfigured() bool

IsConfigured returns whether the provider is configured

func (*MockProvider) Name 

func (m *MockProvider) Name() string

Name returns the provider name

type ModerationLabel added in v1.1.1 

type ModerationLabel struct {
	Name       string  `json:"name"`                 // Moderation label, e.g. Adult, Violence
	Parent     string  `json:"parent,omitempty"`     // Parent category where available
	Confidence float32 `json:"confidence,omitempty"` // Confidence score 0.0-1.0
	Severity   string  `json:"severity,omitempty"`   // Provider-specific severity/likelihood text
}

ModerationLabel stores safe-search / moderation flags reported by providers

type OllamaProvider added in v1.2.0 

type OllamaProvider struct {
	// contains filtered or unexported fields
}

OllamaProvider implements the Provider interface for local Ollama models

func NewOllamaProvider added in v1.2.0 

func NewOllamaProvider() (*OllamaProvider, error)

NewOllamaProvider creates a new Ollama provider instance

func (*OllamaProvider) Detect added in v1.2.0 

func (o *OllamaProvider) Detect(ctx context.Context, img *image.NRGBA, opts *DetectOptions) (*DetectionResult, error)

Detect performs detection using the configured Ollama model

func (*OllamaProvider) IsConfigured added in v1.2.0 

func (o *OllamaProvider) IsConfigured() bool

IsConfigured checks if the provider is properly configured

func (*OllamaProvider) Name added in v1.2.0 

func (o *OllamaProvider) Name() string

Name returns the provider name

type OpenAIProvider 

type OpenAIProvider struct {
	// contains filtered or unexported fields
}

OpenAIProvider implements the Provider interface for OpenAI Vision

func NewOpenAIProvider 

func NewOpenAIProvider() (*OpenAIProvider, error)

NewOpenAIProvider creates a new OpenAI Vision provider instance

func (*OpenAIProvider) Close 

func (o *OpenAIProvider) Close() error

Close closes the OpenAI client (no-op)

func (*OpenAIProvider) Detect 

func (o *OpenAIProvider) Detect(ctx context.Context, img *image.NRGBA, opts *DetectOptions) (*DetectionResult, error)

Detect performs object detection using OpenAI Vision

func (*OpenAIProvider) IsConfigured 

func (o *OpenAIProvider) IsConfigured() bool

IsConfigured checks if the provider is properly configured

func (*OpenAIProvider) Name 

func (o *OpenAIProvider) Name() string

Name returns the provider name

type Provider 

type Provider interface {
	// Detect analyzes an image and returns detection results
	Detect(ctx context.Context, img *image.NRGBA, opts *DetectOptions) (*DetectionResult, error)

	// Name returns the provider name
	Name() string

	// IsConfigured returns true if provider has required credentials
	IsConfigured() bool
}

Provider defines the interface all detection providers must implement

func GetProvider 

func GetProvider(name string) (Provider, error)

GetProvider returns a provider instance by name

type SafeSearchSummary added in v1.1.1 

type SafeSearchSummary struct {
	Labels []ModerationLabel `json:"labels,omitempty"`
	Notes  string            `json:"notes,omitempty"`
}

SafeSearchSummary provides a high-level summary of provider ratings

type TextBlock 

type TextBlock struct {
	Text        string  `json:"text"`                   // Detected text
	Confidence  float32 `json:"confidence"`             // Confidence score
	Language    string  `json:"language,omitempty"`     // Detected language
	BoundingBox *Box    `json:"bounding_box,omitempty"` // Text location
	Type        string  `json:"type,omitempty"`         // TEXT, LINE, WORD, etc.
}

TextBlock represents detected text

type WebDetection 

type WebDetection struct {
	WebEntities             []WebEntity `json:"web_entities,omitempty"`               // Similar entities
	FullMatchingImages      []WebImage  `json:"full_matching_images,omitempty"`       // Exact matches
	PartialMatchingImages   []WebImage  `json:"partial_matching_images,omitempty"`    // Partial matches
	PagesWithMatchingImages []WebPage   `json:"pages_with_matching_images,omitempty"` // Pages containing image
	VisuallySimilarImages   []WebImage  `json:"visually_similar_images,omitempty"`    // Similar images
	BestGuessLabels         []string    `json:"best_guess_labels,omitempty"`          // Best guess descriptions
}

WebDetection represents web search results (Google Cloud Vision)

type WebEntity 

type WebEntity struct {
	EntityID    string  `json:"entity_id"`
	Score       float32 `json:"score"`
	Description string  `json:"description"`
}

WebEntity represents a web entity found

type WebImage 

type WebImage struct {
	URL   string  `json:"url"`
	Score float32 `json:"score,omitempty"`
}

WebImage represents an image found on the web

type WebPage 

type WebPage struct {
	URL                   string     `json:"url"`
	Score                 float32    `json:"score,omitempty"`
	PageTitle             string     `json:"page_title,omitempty"`
	FullMatchingImages    []WebImage `json:"full_matching_images,omitempty"`
	PartialMatchingImages []WebImage `json:"partial_matching_images,omitempty"`
}

WebPage represents a web page containing the image

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.