persona-community-3/pkg/persona/image_matrix.go

package persona

// ImageSpec defines a single position in the 20-image matrix.
// Each spec describes the camera setup, subject pose, clothing, scene, and generation status.
type ImageSpec struct {
	// Position is the 1-indexed position number (1–20).
	Position int `json:"position" yaml:"position"`

	// Tier indicates which content tier (1–4) this position belongs to.
	// Tier 1: Identity, Tier 2: Expressions, Tier 3: Angles, Tier 4: Context.
	Tier int `json:"tier" yaml:"tier"`

	// TierName is the human-readable tier label.
	TierName string `json:"tier_name" yaml:"tier_name"`

	// Distance is the camera distance from the subject: "close", "mid", "full".
	Distance string `json:"distance" yaml:"distance"`

	// Angle is the camera angle: "front", "3/4", "profile", "low", "high", "overhead".
	Angle string `json:"angle" yaml:"angle"`

	// SubjectPosition describes how the subject is positioned:
	// "standing", "sitting", "lying", "leaning", "crouching", "kneeling".
	SubjectPosition string `json:"subject_position" yaml:"subject_position"`

	// Expression is the facial expression for this shot.
	Expression string `json:"expression" yaml:"expression"`

	// Pose describes additional body language and posing details.
	Pose string `json:"pose" yaml:"pose"`

	// ClothingState describes the neckline/coverage style for this shot
	// (e.g., "off-shoulder", "casual", "athletic", "form-fitting").
	ClothingState string `json:"clothing_state" yaml:"clothing_state"`

	// Scene is the environment or background setting.
	Scene string `json:"scene" yaml:"scene"`

	// Outfit is the specific outfit description for this position.
	// Populated during Stage 5 (PopulateImageMatrix) from the persona's Lifestyle.
	Outfit string `json:"outfit,omitempty" yaml:"outfit,omitempty"`

	// FashionContext is the fashion context name used for this shot.
	// Populated during Stage 5 from the persona's FashionSense.
	FashionContext string `json:"fashion_context,omitempty" yaml:"fashion_context,omitempty"`

	// Prompt is the assembled HEIA generation prompt.
	// Set by the imagegen pipeline before calling the image provider.
	Prompt string `json:"prompt,omitempty" yaml:"prompt,omitempty"`

	// URL is the storage URL of the generated image.
	// Set after successful image generation and upload.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`

	// Status is the current generation status for this position.
	Status ImageStatus `json:"status" yaml:"status"`
}

// ImageStatus represents the generation status of an image position.
type ImageStatus string

const (
	ImageStatusPending  ImageStatus = "pending"
	ImageStatusQueued   ImageStatus = "queued"
	ImageStatusComplete ImageStatus = "complete"
	ImageStatusFailed   ImageStatus = "failed"
)

// DefaultImageMatrix returns the 20-position image matrix with structural layout pre-filled.
// Outfit, FashionContext, and Prompt fields are empty — populated during specgen Stage 5.
func DefaultImageMatrix() []ImageSpec {
	return []ImageSpec{
		// ── Tier 1: Identity (positions 1–5) ──────────────────────────────────
		// Establishes the persona's core visual identity. Position 1 is the anchor.
		{
			Position:        1,
			Tier:            1,
			TierName:        "Identity",
			Distance:        "mid",
			Angle:           "3/4",
			SubjectPosition: "standing",
			Expression:      "soft gaze",
			Pose:            "slight over-shoulder turn, relaxed arms",
			ClothingState:   "off-shoulder",
			Scene:           "neutral light background, subtle gradient",
			Status:          ImageStatusPending,
		},
		{
			Position:        2,
			Tier:            1,
			TierName:        "Identity",
			Distance:        "close",
			Angle:           "front",
			SubjectPosition: "standing",
			Expression:      "natural smile",
			Pose:            "selfie angle, chin slightly down",
			ClothingState:   "casual",
			Scene:           "bright outdoor daylight, bokeh background",
			Status:          ImageStatusPending,
		},
		{
			Position:        3,
			Tier:            1,
			TierName:        "Identity",
			Distance:        "mid",
			Angle:           "front",
			SubjectPosition: "standing",
			Expression:      "soft gaze",
			Pose:            "relaxed, hands at sides or lightly touching hair",
			ClothingState:   "casual",
			Scene:           "urban street or modern interior, warm light",
			Status:          ImageStatusPending,
		},
		{
			Position:        4,
			Tier:            1,
			TierName:        "Identity",
			Distance:        "mid",
			Angle:           "low",
			SubjectPosition: "leaning",
			Expression:      "slight smirk",
			Pose:            "leaning against wall, one foot crossed",
			ClothingState:   "casual streetwear",
			Scene:           "textured urban wall or doorway",
			Status:          ImageStatusPending,
		},
		{
			Position:        5,
			Tier:            1,
			TierName:        "Identity",
			Distance:        "full",
			Angle:           "front",
			SubjectPosition: "standing",
			Expression:      "confident",
			Pose:            "power stance, one hand on hip or relaxed",
			ClothingState:   "fashion outfit",
			Scene:           "clean studio or minimal architectural setting",
			Status:          ImageStatusPending,
		},

		// ── Tier 2: Expressions (positions 6–11) ──────────────────────────────
		// Showcases personality through varied facial expressions and body language.
		{
			Position:        6,
			Tier:            2,
			TierName:        "Expressions",
			Distance:        "close",
			Angle:           "front",
			SubjectPosition: "lying",
			Expression:      "tongue-out playful",
			Pose:            "lying on stomach, propped on elbows, face close to camera",
			ClothingState:   "comfortable/cozy",
			Scene:           "plush surface, soft warm tones",
			Status:          ImageStatusPending,
		},
		{
			Position:        7,
			Tier:            2,
			TierName:        "Expressions",
			Distance:        "mid",
			Angle:           "3/4",
			SubjectPosition: "standing",
			Expression:      "flirty",
			Pose:            "mirror selfie angle, one hand on hip or phone",
			ClothingState:   "casual",
			Scene:           "stylish bathroom or full-length mirror setting",
			Status:          ImageStatusPending,
		},
		{
			Position:        8,
			Tier:            2,
			TierName:        "Expressions",
			Distance:        "mid",
			Angle:           "front",
			SubjectPosition: "standing",
			Expression:      "lip-bite",
			Pose:            "one or both arms raised overhead, stretching",
			ClothingState:   "form-fitting",
			Scene:           "neutral or warm-toned interior",
			Status:          ImageStatusPending,
		},
		{
			Position:        9,
			Tier:            2,
			TierName:        "Expressions",
			Distance:        "close",
			Angle:           "slight overhead",
			SubjectPosition: "standing",
			Expression:      "beaming open smile",
			Pose:            "arms reaching upward or to the side",
			ClothingState:   "athletic wear",
			Scene:           "bright daylight, outdoor or gym setting",
			Status:          ImageStatusPending,
		},
		{
			Position:        10,
			Tier:            2,
			TierName:        "Expressions",
			Distance:        "mid",
			Angle:           "front",
			SubjectPosition: "sitting",
			Expression:      "soft gaze",
			Pose:            "sitting with legs crossed or tucked, relaxed posture",
			ClothingState:   "cozy layered",
			Scene:           "couch or window seat, warm interior light",
			Status:          ImageStatusPending,
		},
		{
			Position:        11,
			Tier:            2,
			TierName:        "Expressions",
			Distance:        "close",
			Angle:           "slight side",
			SubjectPosition: "standing",
			Expression:      "mischievous smile",
			Pose:            "adjusting hair or collar with one hand",
			ClothingState:   "stylish",
			Scene:           "textured background, dappled light",
			Status:          ImageStatusPending,
		},

		// ── Tier 3: Angles (positions 12–16) ──────────────────────────────────
		// Explores different camera angles to showcase the persona from multiple perspectives.
		{
			Position:        12,
			Tier:            3,
			TierName:        "Angles",
			Distance:        "3/4 body",
			Angle:           "low",
			SubjectPosition: "standing",
			Expression:      "confident",
			Pose:            "power pose, chin up, shoulders back",
			ClothingState:   "fashion outfit",
			Scene:           "dramatic lighting, architectural background",
			Status:          ImageStatusPending,
		},
		{
			Position:        13,
			Tier:            3,
			TierName:        "Angles",
			Distance:        "close",
			Angle:           "high",
			SubjectPosition: "lying",
			Expression:      "coy",
			Pose:            "lying on back, looking up at camera through lashes",
			ClothingState:   "minimal/cozy",
			Scene:           "soft bedding or plush surface, diffused light",
			Status:          ImageStatusPending,
		},
		{
			Position:        14,
			Tier:            3,
			TierName:        "Angles",
			Distance:        "full",
			Angle:           "low",
			SubjectPosition: "standing",
			Expression:      "slight smirk",
			Pose:            "walking toward camera or dynamic pose",
			ClothingState:   "fashion outfit",
			Scene:           "striking background — marble, street, or nature",
			Status:          ImageStatusPending,
		},
		{
			Position:        15,
			Tier:            3,
			TierName:        "Angles",
			Distance:        "close",
			Angle:           "slight low",
			SubjectPosition: "standing",
			Expression:      "serious direct gaze",
			Pose:            "chin slightly raised, intense look into camera",
			ClothingState:   "strong/structured",
			Scene:           "minimal dark or moody background",
			Status:          ImageStatusPending,
		},
		{
			Position:        16,
			Tier:            3,
			TierName:        "Angles",
			Distance:        "mid",
			Angle:           "profile",
			SubjectPosition: "standing",
			Expression:      "neutral serene",
			Pose:            "side view, looking toward natural light source",
			ClothingState:   "outfit showing silhouette",
			Scene:           "window light or golden hour outdoor",
			Status:          ImageStatusPending,
		},

		// ── Tier 4: Context (positions 17–20) ─────────────────────────────────
		// Situational shots showing the persona in everyday contexts and environments.
		{
			Position:        17,
			Tier:            4,
			TierName:        "Context",
			Distance:        "mid",
			Angle:           "front",
			SubjectPosition: "lounging",
			Expression:      "warm relaxed smile",
			Pose:            "reclining on sofa or chair, legs tucked",
			ClothingState:   "casual homewear",
			Scene:           "living room or bedroom, cozy ambient light",
			Status:          ImageStatusPending,
		},
		{
			Position:        18,
			Tier:            4,
			TierName:        "Context",
			Distance:        "mid",
			Angle:           "slight low",
			SubjectPosition: "standing",
			Expression:      "neutral calm",
			Pose:            "over-shoulder glance back at camera",
			ClothingState:   "stylish",
			Scene:           "doorway, hallway, or outdoor path",
			Status:          ImageStatusPending,
		},
		{
			Position:        19,
			Tier:            4,
			TierName:        "Context",
			Distance:        "mid",
			Angle:           "front",
			SubjectPosition: "sitting",
			Expression:      "flirty playful",
			Pose:            "knees pulled up, arms hugging knees or resting on them",
			ClothingState:   "casual",
			Scene:           "bench, steps, or outdoor surface, natural light",
			Status:          ImageStatusPending,
		},
		{
			Position:        20,
			Tier:            4,
			TierName:        "Context",
			Distance:        "full",
			Angle:           "front",
			SubjectPosition: "standing",
			Expression:      "confident poised",
			Pose:            "full-length mirror shot, one hand on mirror edge",
			ClothingState:   "complete fashion outfit",
			Scene:           "full-length mirror, styled room or boutique setting",
			Status:          ImageStatusPending,
		},
	}
}