Dynamic Image Processing and URL Generation

This document explains how BuddyPress VIP Go implements dynamic image processing using URL query parameters instead of creating multiple static image files. The system leverages VIP's File Hosting Service (FHS) with Photon-like parameters to crop, resize, and optimize images on-demand, with results cached at the CDN level.

For information about how images are initially uploaded and metadata is stored, see Avatar Management and Cover Image Handling. For details on the metadata storage architecture, see Metadata Storage Architecture.

Purpose and Architectural Shift

Traditional BuddyPress creates multiple physical image files for each avatar and cover image (e.g., bpthumb, bpfull sizes). This approach is incompatible with VIP's infrastructure where filesystem operations are restricted or expensive. BuddyPress VIP Go replaces this with a metadata-driven, dynamic image manipulation strategy:

1. Single source file: Only the original uploaded image is stored in VIP FHS
2. Crop coordinates in metadata: Crop parameters are stored in WordPress user/group metadata
3. Dynamic URL generation: URLs are generated with query parameters that instruct VIP FHS how to process the image
4. On-demand processing: Images are cropped/resized when requested, not during upload
5. CDN caching: Processed images are cached by VIP's CDN for performance

Sources: files.php148-256 README.md24-40

URL Generation Flow

The system generates image URLs through two primary code paths: one for avatars and one for cover images. Both paths construct URLs by appending query parameters to the base image URL stored in metadata.

</old_str> <new_str>

Sources: files.php148-256 README.md24-40

URL Generation Flow

The system generates image URLs through two primary code paths, both constructing URLs by appending query parameters to the base image URL stored in metadata.

URL Generation Sequence

Sources: files.php148-256 README.md24-40

URL Generation Flow

The system generates image URLs through two primary code paths: one for avatars and one for cover images. Both paths construct URLs by appending query parameters to the base image URL stored in metadata.

Sources: files.php70-89 files.php106-136 files.php148-256 files.php277-324

Query Parameter System

The plugin uses four primary query parameters that are understood by VIP's File Hosting Service. These parameters follow Photon-like syntax for image manipulation.

Parameter Reference Table

Parameter	Purpose	Format	Example
w	Width clamping (prevents upscaling)	w={pixels}	w=450
crop	Crop region specification	crop={x}px,{y}px,{w}px,{h}px	crop=50px,100px,300px,300px
resize	Output dimensions	resize={width},{height}	resize=150,150
strip	Metadata removal	strip=info	strip=info

Sources: files.php221-239 files.php301-311

Width Clamping (w parameter)

The w parameter prevents upscaling of images uploaded on narrow displays. It clamps the image width before other operations are applied.

The ui_width value is stored during upload files.php410 and conditionally added to URLs only if present files.php222-244

Sources: files.php222-244 files.php354-392

Crop Parameter

The crop parameter specifies the rectangular region to extract from the source image. The format is {x}px,{y}px,{width}px,{height}px where coordinates are in pixels.

For Avatars: The crop coordinates are stored in metadata during upload files.php406-412 with initial values set to cover the full image:

• crop_x: 0 (initial)
• crop_y: 0 (initial)
• crop_w: bp_core_avatar_full_width() (typically 150px)
• crop_h: bp_core_avatar_full_height() (typically 150px)

These values are updated when the user crops the avatar files.php679-738 The URL generation constructs the crop parameter as:

For Cover Images: Cover images use a fixed cropping strategy that extracts the middle 25% vertical portion of the image files.php307:

This crops from x=0, y=25% of image height, with dimensions matching the component's cover image size.

Sources: files.php226-232 files.php307 files.php679-738

Resize Parameter

The resize parameter specifies the final output dimensions after cropping. The format is {width},{height} (no unit suffix).

The dimensions come from the $params array passed to the filter functions, which are ultimately derived from BuddyPress's configured avatar sizes:

• bpthumb: Typically 50x50px
• bpfull: Typically 150x150px

Sources: files.php235 files.php70-89

Strip Parameter

The strip=info parameter removes EXIF and IPTC metadata from the output image. This is important for privacy (removes GPS coordinates, camera model, etc.) and reduces file size.

This parameter is applied to both avatars files.php238 and cover images files.php310

Sources: files.php238 files.php310

Avatar URL Generation

Avatar URLs are generated by vipbp_filter_avatar_urls() which serves as a helper function for both user and group avatars.

Function Hierarchy:

1. vipbp_filter_user_avatar_urls() files.php70-89 - Entry point for user avatars
2. vipbp_filter_group_avatar_urls() files.php106-136 - Entry point for group avatars
3. vipbp_filter_avatar_urls() files.php148-256 - Common URL builder

Key Code Sections:

Metadata Retrieval:

URL Construction:

Example Generated URLs:

For a user avatar uploaded on desktop (no width clamping), cropped to 100x100 at position 50,50, displayed at bpthumb size (50x50):

https://vip-fhs.wpvip.com/uploads/2024/01/avatar.jpg?crop=50px%2C50px%2C100px%2C100px&resize=50%2C50&strip=info

For a user avatar uploaded on mobile (320px display), displayed at bpfull size (150x150):

https://vip-fhs.wpvip.com/uploads/2024/01/avatar.jpg?w=320&crop=0px%2C0px%2C150px%2C150px&resize=150%2C150&strip=info

Sources: files.php70-136 files.php148-256

Cover Image URL Generation

Cover images use a simpler URL generation process since they don't support user-defined cropping. The system applies a fixed cropping strategy that extracts the middle 25% vertical portion of the image.

Cover Image Dimensions by Component:

BuddyPress defines different cover image dimensions for different components:

• XProfile (Users): Typically 1300x300px (can be filtered)
• Groups: Typically 1300x300px (can be filtered)

These dimensions are retrieved via bp_attachments_get_cover_image_dimensions() files.php298

URL Construction Logic:

Example Generated URL:

For a user cover image with default dimensions (1300x300):

https://vip-fhs.wpvip.com/uploads/2024/01/cover.jpg?w=1300&crop=0%2C25%2C1300px%2C300px&strip=info

This URL:

1. Clamps width to 1300px
2. Crops from x=0, y=25% of original height, extracting a 1300x300px region
3. Strips metadata

Sources: files.php277-324

Extensibility: The vipbp_filter_avatar_urls Filter

The plugin provides a filter hook vipbp_filter_avatar_urls that allows developers to modify generated avatar URLs before they are returned. This enables custom image processing parameters or URL modifications.

Filter Parameters:

• $avatar_url (string): The generated URL with query parameters
• $params (array): Avatar parameters including width, height, object type, item_id, etc.
• $meta (array): Stored metadata including url, crop coordinates, ui_width

Example Use Case:

Sources: files.php248

CDN Caching Strategy

Once VIP FHS processes an image URL with query parameters, the result is cached by VIP's CDN. This means:

1. First request: FHS processes the image (crop, resize, strip metadata) - slower
2. Subsequent requests: CDN serves the cached processed image - very fast
3. Cache invalidation: Handled automatically by VIP when source image changes

The cache key is based on the complete URL including all query parameters. Different parameter combinations create different cache entries:

• ?crop=0px,0px,150px,150px&resize=50,50 (cached separately)
• ?crop=0px,0px,150px,150px&resize=150,150 (cached separately)

Benefits:

• No storage overhead for multiple image sizes
• First-request performance cost is one-time per parameter combination
• Automatic cache invalidation when source images are updated
• Reduced storage costs compared to traditional approach

Sources: Referenced in system architecture diagrams but implemented by VIP infrastructure

Comparison: Traditional vs Dynamic Approach

Traditional BuddyPress (Local Filesystem)

Upload Process:

1. User uploads avatar.jpg (800x800px)
2. BuddyPress creates avatar-bpthumb.jpg (50x50px)
3. BuddyPress creates avatar-bpfull.jpg (150x150px)
4. All files stored in /wp-content/uploads/avatars/{user-id}/

Crop Process:

1. User adjusts crop region
2. BuddyPress regenerates avatar-bpthumb.jpg with new crop
3. BuddyPress regenerates avatar-bpfull.jpg with new crop

Display Process:

1. BuddyPress constructs URL to physical file
2. Web server serves static file

Storage: 3+ files per avatar

BuddyPress VIP Go (Dynamic Processing)

Upload Process:

1. User uploads avatar.jpg (800x800px)
2. Plugin stores single file in VIP FHS via wp_handle_sideload() files.php363-369
3. Plugin stores metadata: {url, crop_x:0, crop_y:0, crop_w:150, crop_h:150}

Crop Process:

1. User adjusts crop region
2. Plugin updates metadata only: {crop_x:50, crop_y:100, crop_w:150, crop_h:150} files.php679-738
3. No files created or modified

Display Process:

1. Plugin constructs URL with query parameters
2. VIP FHS processes image on-demand
3. CDN caches and serves result

Storage: 1 file per avatar + metadata record

Trade-offs:

Aspect	Traditional	Dynamic (VIP Go)
Storage	High (multiple files)	Low (single file + metadata)
Crop operation	Slow (file I/O)	Fast (DB write)
First display	Fast (static file)	Slower (processing)
Subsequent displays	Fast (static file)	Fast (CDN cache)
Flexibility	Limited (pre-defined sizes)	High (any size via query params)
VIP compatibility	Poor (filesystem restrictions)	Excellent (designed for VIP)

Sources: files.php336-464 files.php679-738 README.md24-40