Oyyi
Home Documentation

Halftone Effect

Apply a halftone effect to images, simulating the printing technique that uses dots of varying sizes to create gradients.

POST /api/image/halftone

Request Parameters

ParameterTypeRequiredDescription
fileFileYesThe image file to process. Supported formats: JPEG, PNG, WebP, BMP, TIFF.
dot_sizeIntegerNoThe maximum size of the halftone dots in pixels. Range: 2-20. Default: 5.
background_colorStringNoThe background color. Can be a color name (e.g., white, black) or a hex code (e.g., #FFFFFF). Default: white.

Response

Returns the image with the halftone effect applied, in the same format as the input file.

Example Request

    // example.sh
curl -X POST "https://oyyi.xyz/api/image/halftone"   -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@image.jpg" \
  -F "dot_size=5" \
  --output halftone.jpg

Example with Python

    // halftone.py
import requests

url = "https://oyyi.xyz/api/image/halftone"

files = {
    'file': open('image.jpg', 'rb')
}

data = {
    'dot_size': 5
}

response = requests.post(url, files=files, data=data)

# Save the halftone image
with open('halftone.jpg', 'wb') as f:
    f.write(response.content)

Example with JavaScript

    // halftone.js
// Using fetch API
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('dot_size', '5');

fetch('https://oyyi.xyz/api/image/halftone', {
  method: 'POST',
  body: formData
})
.then(response => response.blob())
.then(blob => {
  // Create a URL for the blob
  const url = URL.createObjectURL(blob);

  // Create a link to download the image
  const a = document.createElement('a');
  a.href = url;
  a.download = 'halftone.jpg';
  a.click();

  // Clean up by revoking the URL
  URL.revokeObjectURL(url);
})
.catch(error => console.error('Error:', error));

Halftone Styles

Circle

The classic halftone pattern with circular dots of varying sizes. This is the most common style and works well for most images.

Square

Uses square dots instead of circles. Creates a more digital or pixelated look.

Line

Uses lines of varying thickness instead of dots. Creates a more linear, engraved look.

Diamond

Uses diamond-shaped dots. Creates an interesting alternative to the classic circular pattern.

Color Modes

Mono

Single-color halftone using black dots on a white background (or vice versa). Classic newspaper or comic book style.

CMYK

Four-color process using Cyan, Magenta, Yellow, and Black halftone patterns at different angles. Simulates traditional color printing.

RGB

Three-color process using Red, Green, and Blue halftone patterns. Creates a more digital or screen-based look.

How It Works

The halftone effect simulates the printing technique used in newspapers and magazines:

  1. Image Sampling: The image is divided into a grid based on the spacing parameter.
  2. Intensity Calculation: For each cell in the grid, the average intensity of the corresponding area in the original image is calculated.
  3. Dot Generation: A dot (or other shape) is drawn in each cell with a size proportional to the intensity value.
  4. Color Separation: For color modes other than mono, the process is repeated for each color channel with different angles.

The result is an image composed of dots or shapes of varying sizes that, when viewed from a distance, create the illusion of continuous tones.

Parameter Effects

Dot Size

  • Small (2-5): Fine detail, more subtle effect
  • Medium (6-10): Balanced effect, good for most uses
  • Large (11-20): Bold, exaggerated effect, more abstract

Spacing

  • Small (1-3): Dense pattern, more detail preserved
  • Medium (4-6): Balanced spacing, classic halftone look
  • Large (7-10): Sparse pattern, more abstract appearance

Error Responses

Status CodeDescription
400Bad request. Missing required parameters, invalid dot_size value, invalid spacing value, invalid style, invalid color_mode, invalid background_color, or invalid file format.
413Payload too large. The file size exceeds the maximum allowed limit.
500Internal server error. Something went wrong on the server.

Notes

  • The halftone effect is a classic printing technique that uses dots of varying sizes to create the illusion of continuous tones.
  • Smaller dot sizes and spacing values will preserve more detail but may result in longer processing times.
  • The CMYK color mode creates a more traditional print-like appearance, while RGB is more digital.
  • High-contrast images typically produce the most striking halftone results.
  • The maximum file size allowed is 10MB.
  • Processing time increases with image size and decreases with larger spacing values.
  • For the best results with color halftones, use images with clear, distinct colors.

Use Cases

  • Creating retro or vintage-style images
  • Simulating newspaper or comic book printing
  • Designing posters or album covers with a screen-printed look
  • Creating artistic effects for graphic design projects
  • Generating unique visual assets for branding or marketing
  • Preparing images for actual screen printing or other printing techniques
  • Creating pop art-inspired images in the style of Roy Lichtenstein
Sketch Pixelate