PicasSoft Logo

Welcome to PicasSoft API

Ninja style API documentation

/add-bleed

PUT request. Adds bleed to a PDF file.

{
    "file": "your_file.pdf",
    "bleed_width": 0.5,
}

/impose

PUT request. Imposes a PDF file.

{
    "input_pdf": "your_input_file.pdf",
    "template_pdf": "your_template_file.pdf",
    "is_front": boolean,
    "params": "your_params"
}

/impose-glue

PUT request. Imposes a PDF file with glue.

{
    "input_front_pdf": "your_input_file.pdf",
    "input_back_pdf": "your_back_file.pdf",
    "template_pdf": "your_template_file.pdf",
    "params": "your_params"
}

/impose-lf-cut

PUT request. Imposes a PDF file with a laser cut.

{
    "shape": "rectangular" | "square" | "circle" | "oval" | "custom",
    "round_corners": "1/16" | "1/8" | "1/4" | "1/2",
    "size": [width, height],
    "input_pdf": "your_input_file.pdf",
    "template_pdf": "your_template_file.pdf",
}

/convert-html-to-pdf

PUT request. Converts HTML to a PDF file.

{
    "html_url": "your_html_url",
    "html_string": "your_html_string",
    "html_file": "your_html_file",
}

/white-support-spot

PUT request. Adds a white support spot to a PDF file.

{
    "background": "your_background.pdf",
    "spot": "your_spot.pdf",
}

Documentation

This is the documentation for the PicasSoft API. Below you will find the endpoints and the required parameters for each endpoint.

PicasSoft

Description

This project is a Python-based PDF processing service. It listens for new PDF files in a specified directory, processes them, and saves the output to the local file system. The project uses several Python libraries such as asyncio, os, pathlib, click, dotenv, fitz, and PIL.

Installation

  1. Clone the repository:

    git clone git@github.com:ivangoranov/PicasSoft.git

  2. Install the dependencies:

    pip install -r requirements.txt

Setting Up the Sandbox Folder Structure for Tests and running the service

Windows

  1. Navigate to the latest release of this repository and download the sandbox.exe and PicasSoft.exe file to your local machine.
  2. Run the sandbox.exe file to create the sandbox folder structure.
  3. Make sure that the LOCAL_FILE_SERVICE_ROOT_DIR environment variable in the .env file points to the sandbox_root_dir folder.
  4. Run the PicasSoft.exe file within the directory where your .env file is placed in order to start the service.

Linux

  1. Clone the repository:

    git clone git@github.com:ivangoranov/PicasSoft.git

Features

This project currently supports the following service types:

Bleed

The bleed service type adds a bleed to a PDF file. It takes a PDF file and a bleed width as input, and outputs a new PDF file with the bleed added. The bleed width is specified in inches.

Impose

The impose service type imposes a PDF file onto a template. It takes an input PDF, a template PDF, and an output PDF file path as input, and outputs a new PDF file with the input PDF imposed onto the template.

Running as a REST API

Our application can also be run as a REST API, allowing other applications to interact with it over the network. Here are the steps to run our application as a REST API:

  1. Ensure you have installed all the necessary dependencies listed in the requirements.txt file. You can install them using pip:

    pip install -r requirements.txt

  2. Start the application with the following command:

    python app.py

    This will start the Flask server, and the application will start listening for HTTP requests on localhost port 5000.

API Endpoints

The application provides the following endpoints:

  1. /add-bleed (PUT): Accepts a PDF file and a bleed width as part of the request data, adds bleed to the PDF, and returns the output PDF as part of the response.

  2. /impose (PUT): Accepts two PDF files (input and template) and some parameters as part of the request data, imposes the input PDF onto the template PDF, and returns the output PDF as part of the response.

  3. /convert-html-to-pdf (PUT): Accepts an HTML URL as part of the request data, converts the HTML to a PDF, and returns the output PDF as part of the response.

Example Requests

Here are examples of how to make requests to each of the endpoints in Python, cURL, and PHP:

Add Bleed

This endpoint is used to add a bleed to a PDF file. The input PDF file is modified by adding a bleed of the specified width to each edge of the document. The output PDF file is returned as the response. The bleed width is specified in inches.

URL: /add-bleed

Method: PUT

Data Params:

Success Response:

Example:

/add-bleed endpoint:

Python:

import requests

url = 'http://localhost:5000/add-bleed'
file_path = '/path/to/your/file.pdf'
bleed_width = 0.25
files = {'file': open(file_path, 'rb')}
data = {'bleed_width': bleed_width}
response = requests.put(url, data=data, files=files)

pdf_data = response.content

with open('output.pdf', 'wb') as f:
    f.write(pdf_data)

cURL:

curl -X PUT -F "file=@/path/to/your/file.pdf" -F "bleed_width=0.25" http://localhost:5000/add-bleed > output.pdf

PHP:

<?php
$url = "http://localhost:5000/add-bleed";
$file_path = "/path/to/your/file.pdf";
$bleed_width = 0.25;

$cfile = new CURLFile($file_path);
$data = array("file" => $cfile, "bleed_width" => $bleed_width);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

Impose

This endpoint is used to impose a PDF file onto a template PDF file. The input PDF file is imposed onto the template PDF file according to the specified parameters. The output PDF file is returned as the response.

URL: /impose

Method: PUT

Data Params:

Success Response:

Example:

/impose endpoint:

Python:

import requests
import json

url = "http://localhost:5000/impose"
input_pdf_path = "/path/to/your/input.pdf"
template_pdf_path = "/path/to/your/template.pdf"
output_pdf = "/path/to/output/file.pdf"
params = {
    "canvas": (13, 19),
    "horizontal-repeat": [0, 0],
    "vertical-repeat": [0, 0, 0, 0.50, 0, 0, 0],
    "h-align": ["center", 0], 
    "v-align": ["center", 0],
    "mark-offset": 0.125,
    "mark-length": 0.25,
    "product": {"width": 8.5, "height": 11, "bleed": 0.125},
    "masksize": ["width + bleed", "height + bleed"]

}

with open(input_pdf_path, 'rb') as f1, open(template_pdf_path, 'rb') as f2:
    files = {'input_pdf': f1, 'template_pdf': f2}
    data = {'params': json.dumps(params)}
    response = requests.put(url, files=files, data=data)

print(response.status_code)

Impose Glue

This is the same as Impose, but require an additional parameter `input_back_pdf' which is the back side of the input_pdf. And the back is imposed upside down.

URL: /impose-glue

Method: PUT

Data Params:

Success Response:

Example:

/impose-glue endpoint:

Python:


import requests
import json

url = "http://localhost:5000/impose-glue"
input_pdf_path = "/path/to/your/input.pdf"
input_back_pdf_path = "/path/to/your/input_back.pdf"
template_pdf_path = "/path/to/your/template.pdf"

params = {
    "canvas": (13, 19),
    "horizontal-repeat": [0, 0],
    "vertical-repeat": [0, 0, 0, 0.50, 0, 0, 0],
    "h-align": ["center", 0], 
    "v-align": ["center", 0],
    "mark-offset": 0.125,
    "mark-length": 0.25,
    "product": {"width": 8.5, "height": 11, "bleed": 0.125},
    "masksize": ["width + bleed", "height + bleed"]

}

with open(input_pdf_path, 'rb') as f1, open(input_back_pdf_path, 'rb') as f2, open(template_pdf_path, 'rb') as f3:
    files = {'input_pdf': f1, 'input_back_pdf': f2, 'template_pdf': f3}
    data = {'params': json.dumps(params)}
    response = requests.put(url, files=files, data=data)

print(response.status_code)

Convert HTML to PDF

This endpoint is used to convert an HTML string to a PDF file.

URL: /convert-html-to-pdf

Method: PUT

Data Params:

Success Response:

Example:

/convert-html-to-pdf endpoint:

Python:

import requests

url = "http://localhost:5000/convert-html-to-pdf"
html_string = "<html><body><h1>Hello, World!</h1></body></html>"

options = {
    'page-size': 'Letter',  # Letter, A4, etc. (default 'Letter')
    'margin-top': '0.0in',
    'margin-right': '0.0in',
    'margin-bottom': '0.0in',
    'margin-left': '0.0in',
}

data = {'html_string': html_string, 'options':options}
response = requests.put(url, data=data)

# The PDF data is in the content attribute of the response
pdf_data = response.content

# Write the PDF data to a file
with open('output.pdf', 'wb') as f:
    f.write(pdf_data)

cURL:

curl -X PUT -d "html_string=<html><body><h1>Hello, World!</h1></body></html>" -d "output_pdf=/path/to/output/file.pdf" http://localhost:5000/convert-html-to-pdf

PHP:

<?php
$url = "http://localhost:5000/convert-html-to-pdf";
$html_string = "<html><body><h1>Hello, World!</h1></body></html>";
$output_pdf = "/path/to/output/file.pdf";

$data = array("html_string" => $html_string, "output_pdf" => $output_pdf);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

White Support Spot

This endpoint is used to add a white support spot to a PDF file.

URL: /white-support-spot

Method: PUT

Data Params:

Success Response:

Example:

/white-support-spot endpoint:

Python:

import requests

url = "http://localhost:5000/white-support-spot"
background_pdf_path = "/path/to/your/background.pdf"
spot_pdf_path = "/path/to/your/spot.pdf"

with open(background_pdf_path, 'rb') as f1, open(spot_pdf_path, 'rb') as f2:
    files = {'background_pdf': f1, 'spot_pdf': f2}
    response = requests.put(url, files=files)

print(response.status_code)

cURL:

curl -X PUT -F "background_pdf=@path_to_background.pdf" -F "spot_pdf=@path_to_spot.pdf" http://localhost:5000/white-support-spot > output.pdf

PHP:

<?php
$url = "http://localhost:5000/white-support-spot";
$background_pdf_path = "/path/to/your/background.pdf";
$spot_pdf_path = "/path/to/your/spot.pdf";

$cfile1 = new CURLFile($background_pdf_path);
$cfile2 = new CURLFile($spot_pdf_path);
$data = array("background_pdf" => $cfile1, "spot_pdf" => $cfile2);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

© 2024 PicasSoft. All rights reserved.