majordomo/imagegen/background.go

package imagegen

import "context"

// BackgroundRemovalRequest asks a matting/segmentation backend to cut the
// subject out of an image. Zero values mean "backend default" (ADR-0020).
type BackgroundRemovalRequest struct {
	// Image is the image to process. Required.
	Image Image

	// Net selects the remover's internal network where the backend offers
	// several (rembg: "u2net", "birefnet-general", "isnet-general-use", ...);
	// "" = backend default. This is NOT the provider model id — that is fixed
	// when the BackgroundRemover is minted.
	Net string

	// OnlyMask returns the black/white segmentation mask instead of the
	// cutout — white where the subject is. Useful as an inpainting mask
	// (EditRequest.Mask semantics after inversion: the mask marks the
	// FOREGROUND, an inpaint mask marks the region to REPAINT).
	OnlyMask bool
}

// BackgroundRemovalOption mutates a BackgroundRemovalRequest before it is sent.
type BackgroundRemovalOption func(*BackgroundRemovalRequest)

// WithBackgroundNet selects the remover's internal network.
func WithBackgroundNet(n string) BackgroundRemovalOption {
	return func(r *BackgroundRemovalRequest) { r.Net = n }
}

// WithOnlyMask requests the segmentation mask instead of the cutout.
func WithOnlyMask() BackgroundRemovalOption {
	return func(r *BackgroundRemovalRequest) { r.OnlyMask = true }
}

// Apply returns a copy of the request with all options applied.
func (r BackgroundRemovalRequest) Apply(opts ...BackgroundRemovalOption) BackgroundRemovalRequest {
	for _, opt := range opts {
		opt(&r)
	}
	return r
}

// BackgroundRemover cuts subjects out of images (RGBA PNG with transparent
// background, or the mask alone with OnlyMask).
type BackgroundRemover interface {
	// RemoveBackground returns the cutout (or mask) as a one-image Result.
	RemoveBackground(ctx context.Context, req BackgroundRemovalRequest, opts ...BackgroundRemovalOption) (*Result, error)
}

// BackgroundRemovalModelOption configures a BackgroundRemover at construction
// time. Reserved for future per-model settings.
type BackgroundRemovalModelOption func(*BackgroundRemovalModelConfig)

// BackgroundRemovalModelConfig carries per-model construction settings.
type BackgroundRemovalModelConfig struct{}

// ApplyBackgroundRemovalModelOptions folds options into a config.
func ApplyBackgroundRemovalModelOptions(opts []BackgroundRemovalModelOption) BackgroundRemovalModelConfig {
	var cfg BackgroundRemovalModelConfig
	for _, opt := range opts {
		opt(&cfg)
	}
	return cfg
}

// BackgroundRemovalProvider mints BackgroundRemovers bound to one backend.
type BackgroundRemovalProvider interface {
	// Name is the registry identifier for the provider.
	Name() string

	// BackgroundRemovalModel returns a BackgroundRemover bound to the given
	// id (passed through to the backend verbatim; no catalog validation).
	BackgroundRemovalModel(id string, opts ...BackgroundRemovalModelOption) (BackgroundRemover, error)
}