Auto-grouping AdManage Rules

1. Detect format — using 20+ regex patterns for common naming conventions (_9x16, (Feed), -S, etc.).

2. Normalize filename — clean suffixes, unify separators, lowercase everything, and strip format tags.

3. Group files — combine variations (e.g. feed, story, square,reel) into sets of 2–3 files per group, ensuring unique formats.

4. Classify format — map dimensions or codes into categories:
• square → 1x1
• portrait → 4x5
• vertical → 9x16
• reel → 9x16
• landscape → 16x9

5. Validate — enforce group size (2–3), unique formats, and mixed categories (not all vertical).

6. Detect file type — based on file extension (image vs video).

Filename Normalization Rules

Pre-Processing

1. Upload Suffix Removal: Remove 4-character upload suffixes (e.g., _btLP, _ijCA) before format detection
• Exception: Keep if it's a meaningful word: main, test, prod, beta, demo, live, sale
• Exception: Keep if all letters and same case (likely a word, not random suffix)

Version/Variant Preservation

1. Version Suffix Preservation: Preserve date-like version patterns (e.g., 250905-6, _250905_3)
• Normalization: Convert underscores to hyphens
• Purpose: Keep different versions separate

2. Trailing Number Preservation: Preserve trailing variant numbers before extension
• Purpose: Keep different numbered variants separate

Format Removal

1. Primary Format Removal: Remove the detected format string

2. Additional Format Cleanup:
• Remove explicit format dimensions: _4x5, _9x16 (before extension)
• Remove format dimensions in parentheses: (4X5), (9X16)
• Remove format dimensions with 4-char hash: _4x5_ZKce, _9x16_ntv1

3. Upload Suffix Removal (Post-Format):
• Remove 4-character upload suffixes after format removal
• Same exceptions as pre-processing (meaningful words, same-case words)

Special Handling

1. Instagram Story/Post: Don't remove the number from Instagram story/post patterns (needed for grouping)

Normalization

1. Separator Normalization:
• Unify various separators to hyphens
• Collapse multiple hyphens to single hyphen
• Remove leading/trailing hyphens

2. Case Normalization: Convert to lowercase

3. Extension Handling:
• Ensure extension is present and lowercase
• Remove trailing dots

4. Fallback: If name becomes empty or just extension, create fallback from original name

5. Re-append Preserved Elements:
• Re-append version suffix if preserved
• Re-append trailing number if preserved (normalize separator to hyphen)

Grouping Rules

Group Key Generation

1. Placement-Based Files:
• Detection: Files with feed, story, or stories keywords with separators/spaces
• Group Key: Remove placement keywords, normalize separators
• Purpose: Group files like thebest_feed.png and thebest_stories.png together

2. Platform-Prefixed Files:
• Detection: Files starting with insta or facebook prefix
• Group Key: Remove platform prefix, keep trailing numbers
• Purpose: Group files like Insta content 1_9x16, Insta content 1_4x5 as content-1

3. Standard Format-Based Grouping:
• Group Key: Normalized base name (format removed, normalized)

Group Assignment Rules

1. Type Matching: Items must have the same type (image or video) to be in the same group
• If types don't match, create new group with counter suffix

2. Maximum Group Size: Maximum 3 items per group
• If group is full, create new group with counter suffix

3. Format Uniqueness: Each format can only appear once per group
• If format already exists in group, create new group with counter suffix

4. Unique Key Generation: Use preview URL, fallback to url, fallback to name_index

Format Normalization Rules

Short Code Mapping

1. Square Formats:
• 11, 1x1, sq, g → square

2. Vertical Formats:
• 916, 9x16, vt, story, s → vertical

3. Landscape Formats:
• 169, 16x9 → landscape

4. Portrait Formats:
• 45, 4x5, fi, feed, infeed → portrait

Dimension Mapping

1. Common Pixel Dimensions:
• 1080x1080 → square
• 1080x1920 → vertical
• 1080x1350 → portrait
• 1080x1440 → portrait (3:4 ratio)
• 1920x1080 → landscape
• 1200x628 → landscape
• 628x1200 → vertical
• 1350x1080 → landscape

Ratio-Based Classification

1. Aspect Ratio Rules (for any NxN format):
• Square: ratio ≈ 1 (0.9 to 1.1)
• Vertical: ratio ≤ 0.7 (e.g., 9:16 = 0.56)
• Portrait: 0.7 < ratio < 0.9 (e.g., 4:5 = 0.8)
• Landscape: ratio ≥ 1.5 (e.g., 16:9 = 1.77)
• Default Landscape: 1.1 ≤ ratio < 1.5 (e.g., 4:3 = 1.33)

Format Conversion

1. Separator Normalization: Convert N_N, N:N, N-N to NxN

Validation Rules

Group Size Validation

1. Minimum Size: Group must have at least 2 items

2. Maximum Size: Group must have at most 3 items

Format Validation

1. Format Detection: All items must have a determinable format

2. Format Uniqueness: Each item must have a different format (no duplicates)

3. Format Count: Must have at least 2 different valid formats

Category Validation

1. Category Requirements:
• Special Case: Square + Portrait/Vertical + Landscape combination is always valid
• General Rule: Must have formats from at least 2 different categories
• Categories: portrait, vertical, square, landscape

2. Category Validation: Formats must belong to more than one category
• All items cannot be the same category (e.g., all vertical)

File Type Detection Rules

Image Extensions

• png, jpg, jpeg, gif, webp, heic, heif, svg, bmp, tiff

Video Extensions

• mov, mp4, m4v, avi, mkv, webm, flv, wmv, mpeg, mpg

Return Values

• Returns 'image', 'video', or 'unknown' based on file extension

Notes

• Pattern matching is done on both cleaned and original filenames

• Patterns are evaluated in order (highest priority first)

• Grouping uses normalized base names to create group keys

• Format normalization converts various formats to standard categories: square, vertical, portrait, landscape