Scripting functions¶
Artek Utilities adds eleven functions: seven PDF functions under system.artek and four image functions under system.artek.imagehelper.
Before you start¶
Scope. Every function on this page is available in Gateway scope (gateway scripts and Perspective scripts), Designer scope and Vision Client scope. The scope is the same on Ignition 8.1 and 8.3.
Byte arrays in, byte arrays out. Each function takes the file's contents as a byte array (byte[]), never a file path. Typical ways to get one:
- a file on disk:
system.file.readFileAsBytes(path); - a file uploaded in Perspective:
event.file.getBytes()in the File Upload component'sonFileReceivedevent; - a document stored in a database: the value of a binary (BLOB or VARBINARY) column.
A function that returns a file returns a byte array too. Write it to disk with system.file.writeFile(path, bytes), store it in a database, or hand it to a component.
Lists. Functions that take or return several files use a list of byte arrays. A Python list works as the argument; a returned list can be looped over and indexed like a Python list.
Run them on the gateway when you can. PDF work on large files uses memory and time. In Perspective, scripts already run on the gateway.
Summary¶
| Function | Returns |
|---|---|
system.artek.convertPDFToImage(pdfBytes) |
list of PNG images, one per page |
system.artek.mergeMultiPDF(pdfByteDocs) |
one PDF |
system.artek.splitPDFPages(pdfBytes) |
list of single-page PDFs |
system.artek.compressPDF(pdfBytes[, dpi]) |
a smaller PDF |
system.artek.addWatermark(pdfBytes, watermarkText) |
the PDF with a watermark |
system.artek.extractTextFromPDF(pdfBytes) |
the PDF's text |
system.artek.getPDFMetadata(pdfBytes) |
dictionary of document information |
system.artek.imagehelper.getImageDimensions(imageBytes) |
[width, height] |
system.artek.imagehelper.resizeImage(originalImageBytes, newWidth, newHeight) |
the resized image |
system.artek.imagehelper.processImageWithOrientation(imageBytes) |
the image set upright |
system.artek.imagehelper.getByteArraySize(byteArray) |
size in kilobytes |
PDF functions¶
convertPDFToImage¶
Converts each page of a PDF into a PNG image, so a report or a view can show it.
system.artek.convertPDFToImage(pdfBytes)
| Argument | Type | Description |
|---|---|---|
pdfBytes |
byte array | The PDF to convert. |
Returns: a list of byte arrays. Each element is one page of the PDF as a PNG image, in page order.
Pages are rendered at the PDF's own page size (72 DPI).
Scope: Gateway, Designer, Vision Client.
pdf = system.file.readFileAsBytes("C:/docs/procedure.pdf")
pages = system.artek.convertPDFToImage(pdf)
for i, png in enumerate(pages):
system.file.writeFile("C:/docs/procedure-page-%d.png" % (i + 1), png)
mergeMultiPDF¶
Combines several PDFs into one.
system.artek.mergeMultiPDF(pdfByteDocs)
| Argument | Type | Description |
|---|---|---|
pdfByteDocs |
list of byte arrays | The PDFs to merge. Each element is one PDF. |
Returns: a byte array, the merged PDF. The documents are appended in the order of the list.
Scope: Gateway, Designer, Vision Client.
a = system.file.readFileAsBytes("C:/docs/cover.pdf")
b = system.file.readFileAsBytes("C:/docs/report.pdf")
merged = system.artek.mergeMultiPDF([a, b])
system.file.writeFile("C:/docs/cover-and-report.pdf", merged)
splitPDFPages¶
Splits a PDF into single pages.
system.artek.splitPDFPages(pdfBytes)
| Argument | Type | Description |
|---|---|---|
pdfBytes |
byte array | The PDF to split. |
Returns: a list of byte arrays. Each element is a one-page PDF, in page order.
Scope: Gateway, Designer, Vision Client.
pdf = system.file.readFileAsBytes("C:/docs/report.pdf")
for i, page in enumerate(system.artek.splitPDFPages(pdf)):
system.file.writeFile("C:/docs/report-page-%d.pdf" % (i + 1), page)
compressPDF¶
Makes a PDF smaller by lowering its page resolution.
system.artek.compressPDF(pdfBytes)
system.artek.compressPDF(pdfBytes, dpi)
| Argument | Type | Description |
|---|---|---|
pdfBytes |
byte array | The PDF to compress. |
dpi |
integer, optional | The resolution, in dots per inch, of the compressed pages. Default 300. A lower value gives a smaller file and a less sharp page. |
Returns: a byte array, the compressed PDF.
Each page of the result is an image of the original page (JPEG) at the chosen resolution. Because pages become images, text in the compressed PDF can no longer be selected, searched or read with extractTextFromPDF. Keep the original if you need its text.
Scope: Gateway, Designer, Vision Client.
pdf = system.file.readFileAsBytes("C:/docs/scan.pdf")
small = system.artek.compressPDF(pdf, 150)
print system.artek.imagehelper.getByteArraySize(pdf), "kB before"
print system.artek.imagehelper.getByteArraySize(small), "kB after"
addWatermark¶
Adds a text watermark to every page of a PDF.
system.artek.addWatermark(pdfBytes, watermarkText)
| Argument | Type | Description |
|---|---|---|
pdfBytes |
byte array | The PDF to watermark. |
watermarkText |
string | The text of the watermark. |
Returns: a byte array, the PDF with the watermark added.
The watermark is drawn diagonally across each page in dark blue, bold Helvetica at 36 points. It is placed in a PDF layer (optional content group) named Watermark. PDF viewers differ in how they show layers on screen and in print, so check the result in the viewer your users have. The standard Helvetica font covers Western (Latin) characters; keep the watermark text to those characters.
Scope: Gateway, Designer, Vision Client.
pdf = system.file.readFileAsBytes("C:/docs/drawing.pdf")
marked = system.artek.addWatermark(pdf, "UNCONTROLLED COPY")
system.file.writeFile("C:/docs/drawing-uncontrolled.pdf", marked)
extractTextFromPDF¶
Reads the text of a PDF.
system.artek.extractTextFromPDF(pdfBytes)
| Argument | Type | Description |
|---|---|---|
pdfBytes |
byte array | The PDF to read. |
Returns: a string, the text of the PDF.
It reads the text stored in the PDF. It does not read text from images, so a scanned page with no text layer returns little or no text.
Scope: Gateway, Designer, Vision Client.
pdf = system.file.readFileAsBytes("C:/docs/procedure.pdf")
text = system.artek.extractTextFromPDF(pdf)
print "LOCKOUT" in text.upper()
getPDFMetadata¶
Reads a PDF's document information.
system.artek.getPDFMetadata(pdfBytes)
| Argument | Type | Description |
|---|---|---|
pdfBytes |
byte array | The PDF to read. |
Returns: a dictionary with these keys. Every value is a string.
| Key | Value |
|---|---|
pageCount |
The number of pages, as a string (for example "12"). |
title |
The document title, or "N/A" when the PDF has none. |
author |
The document author, or "N/A" when the PDF has none. |
created |
The creation date as yyyy-MM-dd HH:mm:ss, or "N/A" when the PDF has none. |
Scope: Gateway, Designer, Vision Client.
pdf = system.file.readFileAsBytes("C:/docs/report.pdf")
info = system.artek.getPDFMetadata(pdf)
pages = int(info["pageCount"])
print info["title"], pages, info["created"]
Image functions¶
The image functions read JPEG, PNG, GIF and BMP images.
getImageDimensions¶
Returns an image's width and height.
system.artek.imagehelper.getImageDimensions(imageBytes)
| Argument | Type | Description |
|---|---|---|
imageBytes |
byte array | The image to measure. |
Returns: an integer array, [width, height], in pixels.
Scope: Gateway, Designer, Vision Client.
img = system.file.readFileAsBytes("C:/photos/pump-101.jpg")
size = system.artek.imagehelper.getImageDimensions(img)
print "width", size[0], "height", size[1]
resizeImage¶
Resizes an image to a new width and height.
system.artek.imagehelper.resizeImage(originalImageBytes, newWidth, newHeight)
| Argument | Type | Description |
|---|---|---|
originalImageBytes |
byte array | The image to resize. |
newWidth |
integer | The new width, in pixels. |
newHeight |
integer | The new height, in pixels. |
Returns: a byte array, the resized image, in the same format as the original (JPEG, PNG, GIF or BMP).
The image is scaled to exactly the width and height you pass, so to keep its proportions, compute one from the other (see the example). The resized image has no transparency.
Scope: Gateway, Designer, Vision Client.
img = system.file.readFileAsBytes("C:/photos/pump-101.jpg")
w, h = system.artek.imagehelper.getImageDimensions(img)
newWidth = 800
newHeight = int(round(h * newWidth / float(w)))
small = system.artek.imagehelper.resizeImage(img, newWidth, newHeight)
system.file.writeFile("C:/photos/pump-101-800.jpg", small)
processImageWithOrientation¶
Sets a phone photo upright, using the orientation stored in its metadata.
system.artek.imagehelper.processImageWithOrientation(imageBytes)
| Argument | Type | Description |
|---|---|---|
imageBytes |
byte array | The image to set upright. |
Returns: a byte array, the corrected image.
A phone saves most photos in one direction and records how to turn them in the photo's EXIF metadata. This function reads that orientation, rotates the image by 90, 180 or 270 degrees to match, and returns it without the original EXIF data. Use it on photos taken on a phone and uploaded to a view, before you store or show them.
A second form, processImageWithOrientation(imageBytes, flag), takes a true or false value after the image. Its effect is not documented for 1.0.0; use the one-argument form.
Scope: Gateway, Designer, Vision Client.
# Perspective File Upload component, onFileReceived event
photo = event.file.getBytes()
upright = system.artek.imagehelper.processImageWithOrientation(photo)
system.file.writeFile("C:/photos/" + event.file.name, upright)
getByteArraySize¶
Returns the size of a byte array in kilobytes.
system.artek.imagehelper.getByteArraySize(byteArray)
| Argument | Type | Description |
|---|---|---|
byteArray |
byte array | Any byte array, such as an image or a PDF. |
Returns: an integer, the size in kilobytes (1 kB = 1,024 bytes), rounded down. An array smaller than 1,024 bytes returns 0.
Scope: Gateway, Designer, Vision Client.
img = system.file.readFileAsBytes("C:/photos/pump-101.jpg")
if system.artek.imagehelper.getByteArraySize(img) > 2048:
img = system.artek.imagehelper.resizeImage(img, 1600, 1200)