API Endpoint: POST /api/process

Relevant source files

The following files were used as context for generating this wiki page:

• src/main.rs
• static/script.js
• static/index.html
• README.md
• Cargo.toml
• static/style.css

Introduction

The POST /upload endpoint is the core functional component of the hdrify application. It is responsible for receiving an SDR image, applying an HDR-like effect with an adjustable intensity, and returning the processed image. The entire backend processing logic is encapsulated within this single endpoint, which is built using the Rust warp web framework.

This endpoint is called by the frontend JavaScript when a user uploads an image and adjusts the HDR slider. It performs validation, decodes the image, processes it using an external ImageMagick command-line tool, and sends the resulting image back to the client, base64-encoded within a JSON response. Note that while the README.md refers to this endpoint as POST /api/process, the actual implementation in both the backend and frontend uses the path /upload.

Sources: src/main.rs:180-183, static/script.js:275, README.md:65

Endpoint Definition

Property	Value	Source -
HTTP Method	POST	src/main.rs:181 -
Path	/upload	src/main.rs:180 -

• |
  | Content-Type | application/x-www-form-urlencoded | static/script.js:278 - |

Request Payload

The endpoint expects a form-data payload with two fields. The frontend sends this data as application/x-www-form-urlencoded.

Parameter	Type	Description -
image	string	A base64-encoded string representing the user's uploaded image. This is extracted from a data URL on the frontend. -
hdr_value	float	A floating-point number representing the desired HDR intensity. The frontend slider provides a value between 0.5 and 3.0. The backend defaults to 1.5 if the value is missing or invalid.

Sources: src/main.rs:16-21, static/script.js:271-273, static/index.html:43

Response Payload

The API returns a JSON object with a consistent structure for both success and failure cases.

ProcessResponse Structure

#[derive(Debug, Serialize)]
struct ProcessResponse {
    success: bool,
    message: String,
    image_data: Option<String>, // base64 encoded HDR image
}

Source: src/main.rs:8-13

Fields

Field	Type	Description -
success	boolean	true if the image was processed successfully, false otherwise. -
message	string	A descriptive message indicating the result. Examples: "Image processed successfully", "File too large", "ImageMagick error: ...". -
image_data	string (nullable)	A base64-encoded string of the processed PNG image if success is true. null on failure. -

Processing Workflow

The handle_upload function in src/main.rs orchestrates the entire image processing pipeline.

This diagram illustrates the sequence of operations from receiving the request to sending the response.

Frontend to Backend Sequence

This sequence diagram shows the interaction between the user's browser, the Rust backend, and the ImageMagick CLI.

Validation Logic

Before processing, the backend performs several validation checks.

Sources: src/main.rs:23-66, src/main.rs:135-159

Check	Implementation Detail -
Empty Image Data	Checks if the image_data string from the form is empty. If so, returns an error. -
File Size	The decoded image byte array length is checked against a MAX_SIZE constant of 10MB (10 * 1024 * 1024 bytes). This is also enforced on the frontend. -
Image Format	The is_supported_image_format function checks the magic bytes of the file to ensure it is a JPEG, PNG, or WebP file. This prevents processing of unsupported or non-image files. The frontend also validates by MIME type.

Sources: src/main.rs:24-30, src/main.rs:44-55, src/main.rs:58-65, src/main.rs:135-159, static/script.js:150-164, static/index.html:32

ImageMagick Command

The core image processing is delegated to the magick command-line tool. The backend constructs and executes a command with specific arguments to achieve the HDR effect.

magick \
  <input_file_path> \
  -define quantum:format=floating-point \
  -colorspace RGB \
  -auto-gamma \
  -evaluate Multiply <hdr_value> \
  -evaluate Pow 0.9 \
  -colorspace sRGB \
  -depth 16 \
  -profile 2020_profile.icc \
  <output_file_path>

Argument Breakdown

Argument	Description -
-define quantum:format=floating-point	Prepares the image for high-dynamic-range processing by using a floating-point representation for color values. -

• |
  | -colorspace RGB | Converts the image to a linear RGB colorspace.