Contributing Guidelines

Relevant source files

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

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

This document provides a technical overview of the hdrify project to guide potential contributors. It covers the architecture, frontend and backend components, API specification, and setup instructions. The application is a web-based tool for converting standard dynamic range (SDR) images to high dynamic range (HDR) using an ImageMagick-powered pipeline.

The project is composed of a Rust backend using the warp web server framework and a vanilla HTML, CSS, and JavaScript frontend. This separation allows for focused contributions to either the server-side processing logic or the client-side user experience.

Project Setup

To contribute, you first need to set up the development environment. The project can be run using Docker or locally.

Docker Setup

This is the recommended method for a consistent environment.

1. Build the Docker image: docker build -t hdrify .
2. Run the container: docker run -p 3000:3000 hdrify

Local Setup

Requires Rust and ImageMagick to be installed on your system.

1. Install dependencies (e.g., on macOS): brew install imagemagick
2. Run the application: cargo run

After starting the server, the application will be available at http://localhost:3000.

Sources: README.md:37-47, src/main.rs:182-183

System Architecture

The application follows a simple client-server model. The frontend is responsible for the user interface and interaction, while the backend handles the core image processing logic by interfacing with the ImageMagick command-line tool.

The diagram below illustrates the high-level architecture.

Frontend Development

The frontend is built with vanilla HTML, CSS, and JavaScript, ensuring a lightweight and dependency-free client. All frontend source code is located in the static/ directory.

Sources: README.md:51, static/index.html, static/script.js, static/style.css

Core Components

The user interface is defined in index.html and styled by style.css. The core logic is encapsulated within the HDRify class in script.js.

Component ID	Element Type	Description	Source File
uploadArea	div	Drag-and-drop area for image uploads.	static/index.html:26
imageInput	input	Hidden file input triggered by the upload area.	static/index.html:28
resultImage	img	Displays the processed HDR image.	static/index.html:32
processingOverlay	div	A spinner overlay shown during image processing.	static/index.html:33
hdrSlider	input	Range slider to control the HDR intensity from 0.5 to 3.0.	static/index.html:40
downloadButton	a	Button to download the processed image.	static/index.html:43
resetButton	button	Resets the interface to the initial state.	static/index.html:46

Frontend Class Structure

The HDRify class manages the application's state and user interactions.

This diagram shows the main properties and methods of the HDRify class, which orchestrates all frontend activity.

Sources: static/script.js:1-338

Client-Side Processing Flow

The following sequence diagram details the user interaction flow from uploading an image to seeing the result.

Backend Development

The backend is a lightweight Rust application using the warp framework. Its sole responsibility is to receive image data, process it using ImageMagick, and return the result. The main logic is contained in src/main.rs.

Sources: README.md:50, src/main.rs

Dependencies

Backend dependencies are managed by Cargo and defined in Cargo.toml.

Crate	Version	Purpose
warp	0.3	Web server framework
tokio	1.0	Asynchronous runtime
serde	1.0	Serialization/deserialization framework
base64	0.21	Base64 encoding/decoding
tempfile	3.0	Creating temporary files for processing

Sources: Cargo.toml:6-13

API Endpoint: POST /upload

The server exposes a single endpoint to handle image processing. Note that the implementation in src/main.rs and static/script.js uses /upload, not /api/process as mentioned in the README.md.

Parameter	Type	Description
image	String	Base64-encoded image data (without prefix).
hdr_value	String	The desired HDR intensity (e.g., "1.5").

Sources: src/main.rs:17, 18, 175, static/script.js:255-257

The server responds with a JSON object defined by the ProcessResponse struct.

// Source: src/main.rs:6-11
#[derive(Debug, Serialize)]
struct ProcessResponse {
    success: bool,
    message: String,
    image_data: Option<String>, // base64 encoded HDR image
}

Backend Logic Flow

The handle_upload function orchestrates the entire backend process.

This diagram shows the step-by-step logic inside the handle_upload function, from receiving the request to sending the final response.

Sources: src/main.rs:13-145

The core of the processing is the ImageMagick command pipeline.

# Source: src/main.rs:81-97
magick <input_file> \
    -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>

This command sequence is derived directly from the article mentioned in the project's README.md.

Sources: src/main.rs:81-97, README.md:28-35

Summary

Contributing to hdrify involves working on either the vanilla JavaScript frontend or the Rust backend.

• Frontend contributions would focus on improving the UI/UX in static/index.html, static/style.css, and static/script.js.
• Backend contributions would involve modifying the warp server, the ImageMagick pipeline, or validation logic in src/main.rs.

Ensure any changes are tested using the local or Docker setup. Adhering to the existing architecture and code style will help streamline the contribution process.