Acme Documentation - Read the Docs · ACME service would then return an animated requested ﬁle type. Depending on creation arguments described in this documentation, a ﬁle similar

Acme Documentation

Peter C. Miller

Nov 29, 2020

Contents:

1 Introduction 11.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 Animations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3 SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.4 CDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251.5 fbx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251.6 frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261.7 gif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.8 mp4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281.9 new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291.10 orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351.11 image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.12 progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371.13 thumbnails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371.14 version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

2 Indices and tables 39

i

ii

CHAPTER 1

Introduction

This documentation describes the REST ful Web Application Programming Interface (Web API) supporting the ‘Soft-ware as a Service’ (SaaS) provided by Animated Codes Made Easy LLC, or ‘ACME’.

ACME’s service provides near real time creation of customized animations of any scannable code, including QRcodes.

Standard codes and QR codes (non-animated) can also be created, and are free of charge within certain volumelimitations.

If you are a software developer interested in using ACME’s service, this documentation is for you. If you are not asoftware developer, you’ll probably be happier visiting ACME’s home page: www.acme.codes, or you may just wantto go ahead and make animated codes yourself with ACME’s Coderunner .

This documentation describes the ReST API call sequences for requesting an animated code online.

The root domain of the API described here is https://api.acme.codes

The example workflows described in this documentation will function for anyone without payment; in particular non-animated codes can be generated without any payment (for free). However messages embedded into animated codeswill be prefixed to ACME’s website in a way that limits commercial use but still demonstrates ACME’s real timeencoding ability. All generated demonstration codes are scannable, however the embedded link will only affirm therequested test message rather than contain the original message. To encode messages into animated codes without thisprefixed demonstration restriction, a subscription-based business agreement with ACME must first be paid for.

The majority of API calls made available here can be experimented with by anyone with a browser. Simply try thelinks directly, or copy, edit, and paste them to create your own test codes.

A note on file hosting: The animation files created by this service can be very large. Correspondingly, the length oftime files are available for download is different based on subscription:

1

https://en.wikipedia.org/wiki/Representational_state_transfer

https://en.wikipedia.org/wiki/Web_API

https://en.wikipedia.org/wiki/Software_as_a_service

https://en.wikipedia.org/wiki/Software_as_a_service

https://www.acme.codes

http://www.acme.codes

https://coderunner.acme.codes

https://api.acme.codes

Acme Documentation

- Free demo and retail animations are only available for download for a few hours. Users must manage their filehosting on their own after animation creation.

- Paying subscribers may choose to have their files automatically hosted on our Microsoft Azure based global cloudprovider Content Delivery Network (CDN)

In the rare cases of animations being ‘lost’ since they were not downloaded in time, the ease with which animationsare regenerated from our API solves this problem.

If you have feedback or questions on this documentation, or if you are interested in purchasing bulk quantity near realtime animated codes or QR codes through ACME’s API, please contact [email protected]

Certain design and architectural features of this service are patented under US 10,083,535 B2.

‘QR Code’ is a registered trademark of DENSO WAVE INCORPORATED

1.1 Examples

Here are Rest call sequence examples to generate an Animated QR code through ACME’s API.

1. Basic Animation

2. Custom Image Anim

3. Standard QR code (not animated, free within volume limitations)

** See our SDK for working Python and Javascript examples of code using our API. **

1.1.1 Basic

Here is the minimal 2 step request sequence to receive an animated code from api.acme.codes:

GET: /new GET: /orders/<#>/mp4

1. /new Request an order number by http GET method /new, and receive JSON response from the ACME servicecontaining an Order Number.

2. /orders/#/mp4 Request the product (or any other information) by http GET method referencing the OrderNumber.

For example, a requesting service could ask for an animation to be started by:

GET: https://api.acme.codes/new?msg=ReadingAcmeDocumentationIsFun!

ACME service would return JSON:

{"orderNumber": "1444720642_NLGEDCVP"}

Now, after some time has passed, the client can retrieve up to 5 different animated products: gif, mp4, fbx, png (singleframes), and zip (raw aggregated frames). For example, an mp4 movie file can be attained by:

GET: https://api.acme.codes/orders/1444720642_NLGEDCVP/mp4

ACME service would then return an animated requested file type. Depending on creation arguments described in thisdocumentation, a file similar to this mp4 would be returned:

Note: An immediate resource GET request to an accurate order will initially result in a ‘202 Accepted’ response, andnot a ‘200 OK’ return code because the service has not yet completed creating the file. This response page will containa message clarifying the reason for the temporary inability to return the requested file.

2 Chapter 1. Introduction

https://azure.microsoft.com

https://en.wikipedia.org/wiki/Content_delivery_network

mailto:[email protected]?subject=From%20RTD:%20Interest%20in%20ACME%20Web%20Service

https://patents.google.com/patent/US10083535B2

https://en.wikipedia.org/wiki/JSON

Acme Documentation

Important reminder: Make sure to copy your animations down and place them in your app or CDN or data storagesoon after you create them. Do not put links of the animations you create on api.acme.codes in your apps or CDNs;they will soon be deleted. The animations are only available off of api.acme.codes temporarily; older /orders areautomatically deleted over time. Please remember your harvest period for all files you create on api.acme.codes islimited.

OR

If you become a monthly subscriber, ACME offers its own CDN as supported by Microsoft Azure. This ACME featuresupports global, secure, 24/7/365 hosting of your animation files. See the CDN section of this documentation and thecdn= argument of the /new resource for details.

This completes the Basic Animation workflow; The “Animation with Image” workflow details how to avoid the ‘202Accepted’ response entirely.

1.1.2 Custom Image

Most users of ACME’s API want custom images applied to their generated animations. Th workflow below showshow to do this. Also, since ACME animation generation times can vary significantly based on animation complexity(sub-second to > 2 minutes), this more standard transaction sequence described below provides more options to aclient application.

GET: /new?createAnimation=0 POST: /orders/<#>/image GET: /orders/<#>/progress GET: /orders/<#>/mp4

1. /new?createAnimation=0 (Required for Custom Image Integration) Create the new order but suppress ani-mation creation with createAnimation=0. Animation will start after below image upload call.

2. /orders/<order number>/image (Required for Custom Image Integration) Upload an image to the specificorder just created. This starts the animation creation process.

3. /orders/<order number>/progress (Required) Iteratively GET the server-side runtime informationand order progress of the animation generation by referencing the Order Number. This can be used to display areal time progress bar feedback window for the client. When progress is 100%, the final mp4 URL is also returned.

4. /orders/<order number>/frames/1 (Optional, rarely used) GET the first frame (or any frame, withreasonable correlation to the known server-side progress) by referencing the Order Number. This can be used toprovide accurate visual feedback to the client user of the product as it is being made. Then, when the server-sideprogress is = 100%:

5. /orders/<order number>/mp4-file-info (Optional, rarely used) GET the final product file size. Thisinformation can be used below.

6. Retrieve the final mp4 animation. (Required) This can be done in two ways: /orders/<order number>/mp4 GET the final product (animation, 3d file, frames, etc.) with the genericly named /mp4 resource, or <Finalurl provided in above progress resource> GET the final mp4 with a specific file URL returned inthe above progress resource when progress is 100%.

7. Measure (Optional, rarely used) Measure the local file size as it is streamed in from the above call and compareit to the known full file size. This comparison can be used to accurately provide visual progress bar(s) to the clientregarding file transmission.

8. Retrieve by CDN (Optional) If paying for ACME Content Delivery Network (CDN) subscription, use the URLsupplied in the JSON response from step 1 which contains an absolute path to the hosted animation files. See the CDNsection of this documentation for details.

Below are specific detailed examples of the above process.

1. New: For example, a client application could:

1.1. Examples 3


https://acme.readthedocs.io/en/latest/CDN.html



Acme Documentation

GET: https://api.acme.codes/new?createAnimation=0&msg=ReadingAcmeDocumentationIsFun!



2. Image: Now the users local custom image must be uploaded:

POST: https://api.acme.codes/orders/1444720642_NLGEDCVP/image

The above call will received the image and initiate the animation creation process. ACME service would return JSON:

200 OK

3. Progress: Optionally, now the client application can iteratively retrieve the server-side order progress:

GET: https://api.acme.codes/orders/1444720642_NLGEDCVP/progress


{"progress": 12, "queue": 0}

The client can repeatedly request the progress resource (every few seconds or so) until the “progress” key is 100,indicating that the order is complete. Also, if the “queue” value is non zero, this indicates the service resources areat their maximum capacity since a queue has formed, indicating a slowdown in the usual turnaround time. This canbe communicated to the user to help explain slow or temporarily static progress values.|br| Most importantly, whenprogress is 100 and mp4 file was requested, a URL is provided targeting a specific mp4 file available on the server fordownload or display:

{"progress": 100, "queue": 0, "mp4": "https://api.acme.codes/orders/1595107770_→˓1EGWU128/AcmeCode_441535.mp4"}

4. Frames: Optionally (and rarely used), the remote client application can retrieve arbitrary frames as they becomeavailable. Here are 3 examples of specific frames being requested:

GET: https://api.acme.codes/orders/1444720642_NLGEDCVP/frames/1

ACME service would return a non-animated single png file of frame 1:


Acme Documentation



1.1. Examples 5

Acme Documentation




Acme Documentation

5. Size: Optionally, and rarely used, when reported server-side order “progress” is 100%, the client application canrequest the final product file size:

GET https://api.acme.codes/orders/1444720642_NLGEDCVP/mp4-file-info


{"fileSize": 439441}

6. Animation: Finally, the client application can retrieve the completed animated products. ACME’s API generatesthe following products: mp4, gif, png frames, fbx and zip. The most common retrieval is the mp4 file of an animation,which is best retrieved from the “mp4” data returned from the “progress” resource when progress has completed at100. The “mp4” value contains a specific URL and filename for retrieval:

GET: https://api.acme.codes/orders/1595107770_1EGWU128/AcmeCode_441535.mp4

Alternatively, the mp4 can retrieved from a non-specific, or generic resource:

GET: https://api.acme.codes/orders/1444720642_NLGEDCVP/mp4

In either case, ACME service would then return an animated mp4 file. Depending on creation arguments described

1.1. Examples 7

Acme Documentation

below, a file similar to this would be returned:

Optionally, and rarely used, the client application can display the transmission progress of the final product as it isstreamed from server to client by querying the size of the local streamed file as it arrives and comparing it to the knownfull file size from the above optional mp4-file-info resource.

Important reminder: Make sure to copy your animations down and place them in your app or CDN or data storagesoon after you create them. Do not put links of the animations you create on api.acme.codes in your apps or CDNs;they will soon be deleted. The animations are only available off of api.acme.codes temporarily; they are automaticallydeleted over time. Please remember your harvest period for all files you create on api.acme.codes is limited.

OR

Optionally, if paying for ACME Content Delivery Network subscription, use the URL supplied in the JSON responsefrom step 1 which contains an absolute path to the hosted animation files:

{"orderNumber": "1576574190_8Z0U08JD", "cdnMp4": "https://cdn.api.acme.codes/2019/12/→˓17/e4983b0f-3688-48c1-a49a-f92bda5fb703/AcmeCode_283150.mp4"}

This location can then be embedded in any web page html with global high reliability and availability:

<video loop autoplay muted src="https://cdn.api.acme.codes/2019/12/17/e4983b0f-3688-→˓48c1-a49a-f92bda5fb703/AcmeCode_283150.mp4"></video>

See the CDN section of this documentation for details.

1.1.3 Standard QR Codes

Sometimes folks want to use ACME’s API to generate standard QR codes that are not animated. Why? Several featuressuch as color control, tile shape, transparency, stenciling, anti-aliasing, rotation, and resolution are more controllablethan other online standard (non-animated) QR code generation services.

Also, standard QR Codes are free.

(Within reasonable request volume limitations)

To clarify: Though encoded messages are wrapped in free use demo mode for animations, standard QR code embeddedmessages are not wrapped, and have the direct original message embedded in the code. In other words, animated QRcodes are paywalled, while standard, non-animated, QR codes are completely free and without message wrapping.

Click here to see all the options for QR code generation, in particular people like to use the pixelType argument tocustomize the code tile shapes of standard QR Codes.

There are two methods to getting free standard QR codes form ACME’s API:

1. The Acme Sequence, which is 2-3 API calls. This is the best API approach if you think you may want animated QRcodes in the future, your code will already be able to handle the longer generation times required for animated codecreation and avoid any timeout problems.

2. Single Call sequence. With certain arguments, ACME’s API will return a PNG file directly as a response to the firstcreation API call.

Acme Sequence Here is the ‘most ACME way’ to do a multi-step request sequence to receive a standard (non-animated) code from api.acme.codes:

1. /new?anim=Still&msg=Hello! Request an order number by http GET method /new and specify a non-animated product, and receive JSON response from the ACME service containing an Order Number .

2. /orders/#/frames/1 Request the standard PNG file by http GET method referencing the Order Number.

For example, a requesting service could ask for code by:




./new.html

./new.html#pixeltype


Acme Documentation

GET: https://api.acme.codes/new?msg=Hello&anim=Still



Now, almost immediately, the client can retrieve a standard PNG file:


ACME service would then return a png file:

Note: An immediate resource GET request to an accurate order might initially result in a ‘202 Accepted’ response,and not a ‘200 OK’ return code because the service has not yet completed creating the file. For non-animated requestslike this, it is not usually required to query and order’s progress because the creation time is so short. However, it isstill good practice to check and retry if a 202 response is initially returned.

Single Call By setting both anim=Still and format=png, api.acme.codes will directly return a PNG file of astandard QR code. Note: Due to our high quality rendering pipeline, turnaround time varies and may require a fewseconds before return. Contact [email protected] if you require faster response times for standard QR codecreation API calls, which are available.

1.1. Examples 9

Acme Documentation

GET: https://api.acme.codes/new?msg=Hi!&anim=Still&format=png

1.2 Animations

The web service hosted at api.acme.codes provides a variety of animations that can be applied to any code or QR code.The list of available animations is provided in human-readible (searchable) and machine readible (JSON) formats bythe resources below.

1.2.1 animation-list

The /animation-list page displays a human readable web page for reviewing animation thumbnails and text/tag search-ing available animations. Retail Coderunner pricing is also listed. Each listing is a valid request for the ‘anim’argument of the ‘/new’ resource. Note: Spaces in the animation names should be replaced with underscored in apicalls.

Real time example link:

https://api.acme.codes/animation-list

1.2.2 anims-json

The /anims-json resource returns a machine readable JSON-formatted response flat dictionary of available animations.Each listing is a valid request for the ‘anim’ argument of the ‘/new’ resource. Additional information is also suppliedper animation.

{"Cube": {"blocks": [

[0,2

],[

2,4

],[

4,6

],[

6,8

]],"fast_slow_fast": false,"length": null,"price": 20.0,"slow_fast_slow": false,"tags": [

"tiles","qrcode",

(continues on next page)



https://api.acme.codes/animation-list

Acme Documentation

(continued from previous page)

"rotate","image","2d","cube"

],...

}


https://api.acme.cdes/anims-json

anims-json can return a list limited to animations with matching tags. Here is a call for animations that support takingan input image:

/anims-json?tags=image

Here is a call for only animations that take an input image and are spinning animations:

/anims-json?tags=image,spin


https://api.acme.codes/anims-json?tags=image

1.3 SDK

Software Development Kit

Here are working examples of client-side software running remotely and accessing api.acme.codes to attain animatedor standard QR codes.

Animated QR Code Creation - Python

Animated QR Code Creation - Web Page (Html & Javascript)

Animated QR Code Creation - Web Page with CDN (Html & Javascript)

Animated QR Code Creation with Image Upload - Python

Animated QR Code Creation with Image Upload - Web Page (Html & Javascript)

Standard QR Code Retrieval - Python

Standard QR Code Retrieval - Web Page Html

Note: All source code on this page, executable or not, is declared free under the standard MIT license. This licenseis present in all downloads referenced here, but removed from the inline web page listing to aid readability.

1.3.1 Animated QR Code Creation - Python

acmeAnimationClient.py

This Python script which will make a new request for an animated QR code, check on the progress, and then downloadthe mp4 animation when it is complete. This script depends on the requests module, so make sure that is presentor pip install the requests module on your system first.

1.3. SDK 11

https://api.acme.codes/anims-json

https://api.acme.codes/anims-json?tags=image

https://en.wikipedia.org/wiki/MIT_License

Acme Documentation

Note the design pattern of ‘request, check progress until complete, retrieve’ is required since animation generationtimes exceed the standard timeout periods of internet web service calls.

Download or read acmeAnimationClient.py

1.3.2 Animated QR Code Creation - Web Page (Html & Javascript)

acmeWebAnimationClient.html acmeWebAnimationClient.js

These files define a web page which dynamically queries api.acme.codes for an animation via chained xmlhttp calls.

Note the design pattern of ‘request, check progress until complete, retrieve’ is required since animation generationtimes exceed the standard timeout periods of internet web service calls.

Download or read acmeWebAnimationClient.html

Download or read acmeWebAnimationClient.js

or click here to load and run the page in your browser now.

1.3.3 Animated QR Code Creation - Web Page with CDN (Html & Javascript)

acmeWebAnimationClientCDN.html acmeWebAnimationClientCDN.js

These files define a web page which dynamically queries api.acme.codes for an animation via chained xmlhttp calls.The final product is loaded from ACME’s Content Delivery Network at cdn.api.acme.codes. See the CDN section ofthis documentation for more details.

Download or read acmeWebAnimationClientCDN.html

Download or read acmeWebAnimationClientCDN.js

or click here to load and run the CDN demo page in your browser now.

1.3.4 Animated QR Code Creation with Image Upload - Python

acmeAnimationClientImageUpload.py

This Python script is identical to the Animated QR Code Creation except it has the additional step of uploading acustom image to the order. Uploading a custom image automatically triggers a re-processing of the order, so thedevelopment code pattern is:

“get new order #, upload image to order, check progress, download mp4”

The advantage of uploading a custom image after order creation is that the image can be uploaded privately, but thedisadvantage is a second call must be made after order creation to upload the image. This is in contrast to providinga custom image at order creation time; in this case the advantage is that only one call must be made to create theanimation, but the disadvantage is that the image must be published over the web in advance of order creation via theimg1 argument. See documentation on the /new resource.

Download or read acmeAnimationClientImageUpload.py

1.3.5 Animated QR Code Creation with Image Upload - Web Page (Html &Javascript)

acmeWebAnimationClientImageUpload.html acmeWebAnimationClientImageUpload.js


./_static/acmeWebAnimationClient.html



./_static/acmeWebAnimationClientCDN.html

Acme Documentation

This example set is the same as the above Web Animated QR Code Creation example, but with the additional feature ofa local file selection button and upload button which updates the order’s image file by the Api’s /orders/#/imageresource.

Download or read acmeWebAnimationClientImageUpload.html

Download or read acmeWebAnimationClientImageUpload.js

or click here acmeWebAnimationClientImageUpload.html to load and run the page in your browser now.

1.3.6 Standard QR Code Retrieval - Python

acmeWebStandardCodeClient.py

This Python script does a direct retrieval of a standard (non-animated) QR code from api.acme.codes. Please note thatusage of this resource does not require any Api key and is free of charge within certain volume limitations. ACMEreserves the right to suppress or deny service to users utilizing high usage volumes (~10-20 per hour) without payment.Paid for subscriptions have much higher volume limits.

Download or read acmeStandardCodeClient.py

1.3.7 Standard QR Code Retrieval - Web Page Html

acmeWebStandardCodeClient.html

This simple Html file simply defines an image on the page that uses a remote resource on api.acme.codes that triggersa QR code to made dynamically.

Note that because only a single image file in png format is requested, the turnaround time is quite sort, and can behandled within the scope of normal internet service calls. This is unlike requesting animations, which exceed thetimeline of standard web service calls; api requests for animations must first query for progress completion before thefinal animated files are retrieved.

Obviously this is not the recommended approach to using the api.acme.codes, since the QR code image file is beingmade from scratch each time the page is viewed. Since ACME should never be considered as a Content DeliveryNetwork (CDN), the proper approach would be to capture such images from api.acme.codes first and then store themon a CDN or web server. However, for educational purposes of this SDK kit, the illustration shows how certain callsapi.acme.codes can be easily implemented.

Download or read acmeWebStandardCodeClient.html

or click here acmeWebStandardCodeClient.html to load and run the page in your browser now.

1.3.8 read acmeAnimationClient.py

import osimport requestsfrom os.path import joinfrom time import sleep

# Setup Request for animationrequest_object = requests.Session()new_anim_request_url = (

'https://api.acme.codes/new?msg=DemoMessage' # Baseline request'&gif=0' # Suppress gif for speed'&fbx=0' # Suppress fbx for speed


1.3. SDK 13

./_static/acmeWebAnimationClientImageUpload.html

./_static/acmeWebStandardCodeClient.html

Acme Documentation


'&mp4=1''&xres=400' # since you're a developer...'&yres=400' # ...let's make the resolution better than default# Below: Optional: provide a custom published image to the animation# '&img1=https://some.image/somehere/on/the/internet.png'

)

# Send anim request, get order # in returnorder_request_response = request_object.get(new_anim_request_url)if order_request_response.status_code != 200:

print('Problem with api call: ' + new_anim_request_url)import syssys.exit()

new_order_data = order_request_response.json()print ('The new order number is: ' + new_order_data['orderNumber'])

# Query the api to know when it is completeprogress_url = ('https://api.acme.codes/orders/' +

new_order_data['orderNumber'] +'/progress')

percent_complete = 0while percent_complete < 100:

sleep(2) # Anims take time, be reasonableprogress_response = request_object.get(progress_url)progress_info = progress_response.json()print(str(progress_info['progress']) +

'% complete, currently in stage "' +progress_info['stage'] + '"')

percent_complete = progress_info['progress']print(str(progress_info['progress']) + '% complete')

# Grab the mp4 file and save it in current directorymp4_request = request_object.get(progress_info['mp4'])drop_image_file = join(join(os.getcwd(), 'DemoMp4FromAcme.mp4'))print('Saving file to: ' + drop_image_file)with open(drop_image_file, 'wb') as file_handle:

for chunk in mp4_request.iter_content(4096):file_handle.write(chunk)

print ('Done.')

1.3.9 read acmeWebAnimationClient.html

<!DOCTYPE html><html lang="en"><head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><script src="acmeWebAnimationClient.js"></script>

<style>body, table {text-align: center;margin-left: auto;margin-right: auto;}



Acme Documentation


</style></head><body>

<h1>ACME SDK<br>Api Demo Web Page</h1><br>This page will automatically load a dynamically created animatedQR code from the API at api.acme.codes.<br>Reload to restart.<br><br><br>The order number is: <b id="orderNumber">--</b><br>Animation Progress: <b id="orderProgress"></b><br>Animation Stage: <b id="orderStage"></b><br><br><table>

<tr><td><video id="mp4Animation"muted autoplay loop src=""></td>

</tr></table>

</body></html>

1.3.10 read acmeWebAnimationClientCDN.html


<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><script src="acmeWebAnimationClientCDN.js"></script>

<style>body, table {text-align: center;margin-left: auto;margin-right: auto;}

</style></head><body>

<h1>ACME SDK<br>Api Demo Web Page for CDN</h1><br>This page will automatically load a dynamically created animated QR codefrom the API at api.acme.codes.<br><br><b>Note this example shows how to load the animation file hosted on ACME's CDN

→˓network.</b><br><br>Reload to restart.<br><br><br>The order number is: <b id="orderNumber">--</b><br>Animation Progress: <b id="orderProgress"></b><br>Animation Stage: <b id="orderStage"></b><br><br><table>

<tr>(continues on next page)

1.3. SDK 15

Acme Documentation


<td><video id="mp4Animation"muted autoplay loop src=""></td>

</tr></table>

</body></html>

1.3.11 read acmeWebAnimationClient.js

function getQrCode(){submitAnimationRequest();}

function submitAnimationRequest(){// Send request for new animation// and retrieve order number responselet orderRequest = getAbstractedXmlObj();orderRequest.tgtUrl = (

'https://api.acme.codes/new?msg=AcmeSDKJsApiExample&' +'&anim=Spin' + // Spin is a fast demo'&xres=450' + // higher than default resolution'&yres=450' + // higher than default resolution'&gif=0' + // gif creation is slow'&fbx=0' + // fbx not needed for demo'&mp4=1' // mp4 is fastest / best);

orderRequest.onreadystatechange = function(){if (orderRequest.readyState === 4 && orderRequest.status === 200)

{let orderRequestJson = JSON.parse(orderRequest.responseText);document.getElementById('orderNumber').innerHTML =

orderRequestJson.orderNumber;queryAndUpdateProgress();}

};orderRequest.open('GET', orderRequest.tgtUrl);orderRequest.send();}

function queryAndUpdateProgress()// Update progress until 100%{let progressRequest = getAbstractedXmlObj();progressRequest.tgtUrl = (

'https://api.acme.codes/orders/' +document.getElementById('orderNumber').innerHTML +'/progress');

progressRequest.onreadystatechange = function(){if (progressRequest.readyState === 4 && progressRequest.status === 200)



Acme Documentation


{let orderProgressJson = JSON.parse(progressRequest.responseText);document.getElementById('orderProgress').innerHTML =

orderProgressJsonprogress_info['mp4'].progress + "%";

document.getElementById('orderStage').innerHTML =orderProgressJson.stage;

if (orderProgressJson.progress === 100){retrieveMp4Animation();}

else{// update every 3 secondssetTimeout(queryAndUpdateProgress, 3000);}

}};

progressRequest.open('GET', progressRequest.tgtUrl);progressRequest.send();}

function retrieveMp4Animation(){mp4Animation = document.getElementById("mp4Animation");mp4Animation.setAttribute("src", orderProgressJson.mp4);}

document.addEventListener('DOMContentLoaded',function(event){// Trigger auto-updating of animated qr codegetQrCode();}

);

function getAbstractedXmlObj(){var xmlhttp;if (window.XMLHttpRequest)

{xmlhttp = new XMLHttpRequest();}else

{xmlhttp = new ActiveXObject('Microsoft.XMLHTTP');}return xmlhttp;}

1.3.12 read acmeWebAnimationClientCDN.js

let orderRequestJson = null;



1.3. SDK 17

Acme Documentation


function submitAnimationRequest(){// Send request for new animation// and retrieve order number responselet orderRequest = getAbstractedXmlObj();

orderRequest.tgtUrl = ('https://api.acme.codes/new?msg=AcmeSDKJsApiCDNExample&' +'&anim=Spin' + // Spin is a fast demo'&xres=450' + // higher than default resolution'&yres=450' + // higher than default resolution'&gif=0' + // gif creation is slow'&fbx=0' + // fbx not needed for demo'&mp4=1' + // mp4 is fastest / best'&cdn=1' + // Request CDN delivery'&apiKey=6d3873dc-af01-4cc0-bbb2-0f3537b21f80' // CDN requests requires an

→˓apiKey.// Note the above api key is ACME's locked test apiKey, but with CDN permissions);


{orderRequestJson = JSON.parse(orderRequest.responseText);document.getElementById('orderNumber').innerHTML =





progressRequest.onreadystatechange = function(){if (progressRequest.readyState === 4 && progressRequest.status === 200)


orderProgressJson.progress + "%";document.getElementById('orderStage').innerHTML =

orderProgressJson.stage;if (orderProgressJson.progress === 100)

{retrieveMp4Animation();}

else{



Acme Documentation


// update every 3 secondssetTimeout(queryAndUpdateProgress, 3000);}

}};


function retrieveMp4Animation(){mp4Animation = document.getElementById("mp4Animation");mp4Animation.setAttribute("src", orderRequestJson.cdnMp4)}


);

function getAbstractedXmlObj(){var xmlhttp;if (window.XMLHttpRequest)



1.3.13 read acmeStandardCodeClient.py

import osimport requestsfrom os.path import join

# Setup Request for animationrequest_object = requests.Session()code_request_url = (

'https://api.acme.codes/new?msg=DemoMessage' # Baseline request'&format=png' # request standard image response'&anim=Still' # and no animation

)

# Send code request, get png image file in returncode_request_response = request_object.get(code_request_url)if code_request_response.status_code != 200:

print('Problem with api call: ' + code_request_url)import syssys.exit()

# Save the png file in current directory(continues on next page)

1.3. SDK 19

Acme Documentation


drop_image_file = join(join(os.getcwd(), 'DemoPngFromAcme.png'))print('Saving file to: ' + drop_image_file)with open(drop_image_file, 'wb') as file_handle:

for chunk in code_request_response.iter_content(4096):file_handle.write(chunk)

print('Done.')

1.3.14 read acmeWebStandardCodeClient.html


<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><style>

body, table {text-align: center;margin-left: auto;margin-right: auto;}

</style></head><body><h1>ACME SDK<br>Api Demo Web Page</h1><br>This page will automatically load a dynamically created standard QR code from the API→˓at api.acme.codes.<br>Reload to refresh.<br><br><br><table><tr><td><img src="https://api.acme.codes/new?msg=AcmeSDKJsApiExample&anim=Still&format=png"></td></tr></table></body></html>

1.3.15 read acmeAnimationClientImageUpload.py

import osimport requestsfrom os.path import joinfrom time import sleep

ACME_API_DOMAIN = 'https://api.acme.codes'

# Setup Request for animationrequest_object = requests.Session()new_anim_request_url = (

ACME_API_DOMAIN +



Acme Documentation


'/new?msg=DemoMessage' # Baseline request'&gif=0' # Suppress gif for speed'&fbx=0' # Suppress fbx for speed'&mp4=1''&xres=400' # since you're a developer...'&yres=400' # ...let's make the resolution better than default'&anim=Spin' # Simplest demo animation'&createAnimation=0' # Let's not start animation creation until after image

→˓is uploaded)

# Send anim request, get order # in returnorder_request_response = request_object.get(new_anim_request_url)if order_request_response.status_code != 200:

print('Problem with api call: ' + new_anim_request_url)import syssys.exit()

new_order_data = order_request_response.json()

print('The new order number is: ' + new_order_data['orderNumber'])

# Upload a local custom image to the server after order creationlocal_img_file = '/a/path/to/a/file/on/your/system/uploadMe.jpg'# local_img_file = 'C:\\Users\\Peter C. Miller\\Pictures\\PeterMillerAtDWA.JPG'

image_upload_url = (ACME_API_DOMAIN +'/orders/' +new_order_data['orderNumber'] +'/image')

files = {'ufile': open(local_img_file, 'rb')}image_post_response = requests.post(image_upload_url, files=files)print(image_post_response)

if image_post_response.status_code == 200:print('Image uploaded ok')

else:print('Problem uploading image: ' +

str(image_post_response.status_code) + '\n' +str(image_post_response.text))

# Query the api to know when it is completeprogress_url = (ACME_API_DOMAIN + '/orders/' +

new_order_data['orderNumber'] +'/progress')

percent_complete = 0progress_info = {'progress': 0}while percent_complete < 100:

sleep(2) # Anims take time, be reasonableprogress_response = request_object.get(progress_url)progress_info = progress_response.json()print(str(progress_info['progress']) +

'% complete, currently in stage "' +progress_info['stage'] + '"')

percent_complete = progress_info['progress'](continues on next page)

1.3. SDK 21

Acme Documentation


print(str(progress_info['progress']) + '% complete')

# Grab the mp4 file and save it in current directory

mp4_request = request_object.get(progress_info['mp4'])drop_image_file = join(join(os.getcwd(),

'DemoAnimationWithCustomImage.mp4'))print('Saving file to: ' + drop_image_file)with open(drop_image_file, 'wb') as file_handle:

for chunk in mp4_request.iter_content(4096):file_handle.write(chunk)

print('Done.')

1.3.16 read acmeWebAnimationClientImageUpload.html

<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><script src="acmeWebAnimationClientImageUpload.js"></script><style>

body, table {text-align: center;margin-left: auto;margin-right: auto;}

</style></head>

<body><h1>ACME SDK<br>Api Demo Web Page<br>with Image Upload</h1><br>This page will automatically create a new order for an animated QR codefrom the API at api.acme.codes.<br><br>In addition, buttons tied to xmlhttp objects add support for a local custom image

→˓file to be specified and then uploaded.<br><br>After the image has been uploaded, the animation will be started.<br><br>After progress is complete, the image will be displayed below.<br><br>Reload to restart with a fresh new order.<br><br><br>The order number is: <b id="orderNumber">--</b><br><br><input type="file" id="acmeUploadFile" /><button type="button" onclick="uploadImageWrapper()">Upload Image</button><br><br>Animation Progress: <b id="orderProgress"></b><br><br>Animation Stage: <b id="orderStage"></b><br><br><table>

<tr><td>

<video id="mp4Animation" muted autoplay loop src=""></video>(continues on next page)


Acme Documentation


</td></tr>

</table></body></html>

1.3.17 read acmeWebAnimationClientImageUpload.js

let orderRequestJson = null;let mp4Animation = null;


function submitAnimationRequest(){// Send request for new animation// and retrieve order number responselet orderRequest = getAbstractedXmlObj();orderRequest.tgtUrl = (

'https://api.acme.codes/new?msg=AcmeSDKJsApiExample&' +'&anim=Spin' + // Spin is a fast demo'&xres=450' + // higher than default resolution'&yres=450' + // higher than default resolution'&gif=0' + // gif creation is slow'&fbx=0' + // fbx not needed for demo'&mp4=1' + // mp4 is fastest / best'&createAnimation=0' // Don't start on creation, let image upload start animation);


{orderRequestJson = JSON.parse(orderRequest.responseText);document.getElementById('orderNumber').innerHTML =





progressRequest.onreadystatechange = function()(continues on next page)

1.3. SDK 23

Acme Documentation


{if (progressRequest.readyState === 4 && progressRequest.status === 200)


orderProgressJson.progress + "%";document.getElementById('orderStage').innerHTML =

orderProgressJson.stage;if (orderProgressJson.progress === 100)

{retrieveMp4Animation(orderProgressJson.mp4);}

else{// update every 3 secondssetTimeout(queryAndUpdateProgress, 3000);}

}};


function retrieveMp4Animation(mp4Url){mp4Animation = document.getElementById("mp4Animation");mp4Animation.setAttribute("src", mp4Url)}


);

function getAbstractedXmlObj(){let xmlhttp = null;if (window.XMLHttpRequest)



function uploadImageWrapper(){let a = document.getElementById('acmeUploadFile');uploadImage(

a.files[0],orderRequestJson.orderNumber)

}

function uploadImage(file, order)(continues on next page)


Acme Documentation


{let url = 'https://api.acme.codes/orders/' + order + '/image';let xhr = new XMLHttpRequest();let fd = new FormData();xhr.open('POST', url, true);xhr.onreadystatechange = function()

{if (xhr.readyState === 4 && xhr.status === 200)

{// Every thing ok, file uploaded, now// clear mp4 field and other output fields and then...if (mp4Animation != null)

{mp4Animation.src = '';}// ...update progress and reload when donequeryAndUpdateProgress();}

};fd.append('ufile', file);xhr.send(fd);}

1.4 CDN

Content Delivery Network

ACME provides final animation product file hosting (mp4, gif, fbx, png, zip) in the cloud for paying subscribers.This allows for 24/7/365 global secure availability of created animation files. Our current Cloud Service Provider isMicrosoft Azure. Our CDN subdomain endpoints are:

https://cdn.api.acme.codes

https://acme.azureedge.net

https://acmeapicdn.z13.web.core.windows.net

Each of the above endpoints references the same data source.

ACME’s CDN hosting is a separate additional offering from the standard ACME workflow of creating animation filesin /orders. To review subscriber options, an ACME subscriber can:

1. Utilize the /new resource to create animations (mp4, gif, etc.) which are available in temporary /ordersresources. It is up to the subscriber to download the animation product files and host them where they like, since allcontent in the /orders resource is only temporarily available.

2. Optionally, ACME subscribers can pay for additional services for automated publication of animations to our CDN.This support is essentially permanent global hosting of animations, so long as the subscription is active.

See documentation on the cdn flag in the /new resource on how to implement automated animation product publicationon our CDN.

Please email [email protected] for details on rates and sign up for CDN subscription.

1.5 fbx

/orders/<order number>/fbx

1.4. CDN 25

https://cdn.api.acme.codes

https://acme.azureedge.net

https://acmeapicdn.z13.web.core.windows.net

https://acme.readthedocs.io/en/latest/new.html#cdn

mailto:[email protected]

Acme Documentation

FBX files are an industry standard file format for exchanging animated 3d files between 3d apps. This data is notrendered images, but rather the original 3d scene information. Since no rendering or encoding is necessary, thisACME product take very little time to complete within the request pipeline.

1.5.1 fbx

This resource returns the complete animated FBX binary stream. There is a high variability of time to completion asdriven by animation complexity, including times that may exceed the timeout period of some browsers. It is thereforerecommended to query orders/[OrderNumber]/progress resource first, and after progress has reached a value of 100,then request the fbx file. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/fbx

1.5.2 fbx/[timestamp]

This resource is an alias to /orders/[#]/fbx. This is a convenience resource which is helpful in some programmaticcircumstances to bypass the caching mechanism of client-side frameworks. By putting any timestamp (TS) value afterfbx, the client code is forced - through this resource alias - to always get the latest /orders/[#]/fbx. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/fbx/1464382911

1.5.3 fbx-file

This resource returns the same fbx stream as the above, but when called from within a browser, a “File Save As..’dialog box will appear asking the user where they would like to download the remote file to. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/fbx-file

1.5.4 fbx-file-info

This resource returns a JSON-formatted response containing a ‘fileSize’ key:value pair. The value of fileSize is zerountil the file creation is completed, at which point it is permanently the file size of the finished fbx animation file.Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/fbx-file-info

Example return value:

{"fileSize": 1124656}

1.6 frames

/orders/<order number>/frames/<frame number>


https://en.wikipedia.org/wiki/FBX

Acme Documentation

1.6.1 png

This resource returns a single frame png file corresponding to the frame number of the animation. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/frames/33

1.6.2 zip

ACME also provides access to zip files containing all raw frames of an aniamtion in png format. Access to thisresource is limited to customers who have entered into subscription contracts with ACME.

1.7 gif

/orders/<order number>/gif

Gif files have two advantages over other formats. First, gif format is the most commonly known animation softwareformat, requiring no complex or hardware enabled codecs. As a result, gif files are displayable by almost any softwareand is arguably the most universally readable animated file format. Gif also supports transparency. Gif files haveseveral disadvantages over other formats; they are slow to create, the final file size is very large for the length of timeshown, and the timing of the playback is imprecise.

1.7.1 gif

This resource returns the complete animated gif binary stream. Gif is the most slowly completed format of the ani-mation formats provided by ACME. Therefore, it is always recommended to query orders/[OrderNumber]/progressresource first, and after progress has reached a value of 100, then request the gif file. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/gif

1.7.2 gif/[timestamp]

This resource is an alias to /orders/[#]/gif. This is a convenience resource which is helpful in some programmaticcircumstances to bypass the caching mechanism of client-side frameworks. By putting any timestamp (TS) value aftergif, the client code is forced - through this resource alias - to always get the latest /orders/[#]/gif. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/gif/1464382911

1.7.3 gif-file

This resource returns the same gif stream as the above, but when called from within a browser, a “File Save As..’dialog box will appear asking the user where they would like to download the remote file to. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/gif-file

1.7. gif 27

https://en.wikipedia.org/wiki/GIF

https://en.wikipedia.org/wiki/Codec

https://en.wikipedia.org/wiki/GIF

Acme Documentation

1.7.4 gif-file-info

This resource returns a JSON-formatted response containing a ‘fileSize’ key:value pair. The value of fileSize is zerountil the file creation is completed, at which point it is permanently the file size of the finished gif animation file.Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/gif-file-info


{"fileSize": 1148656}

1.8 mp4

/orders/<order number>/mp4

Mp4 files are the most common and popular ACME deliverable for completed animation files. Mp4 files are the bestcombination of small size and system display compatability - though still not as widely compatible as gif files, whichare almost universally displayable. Mp4 files also support much more precise timing during playback than gifs, andalso can support embedded sound.

1.8.1 mp4

This standard mp4 resource returns the complete animated mp4 binary stream. Other than individual renderedframes, mp4 is the most quickly completed format of the animation formats provided by ACME. After framesare created, mp4 files are usually generated in less than a second. Still, it is always recommended to query or-ders/[OrderNumber]/progress resource first, and after progress has reached a value of 100, then request the mp4 file.Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/mp4

1.8.2 mp4/[timestamp]

This resource is an alias to /orders/[#]/mp4. This is a convenience resource which is helpful in some programmaticcircumstances to bypass the caching mechanism of client-side frameworks. By putting any timestamp (TS) value aftermp4, the client code is forced - through this resource alias - to always get the latest /orders/[#]/mp4. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/mp4/1464382911

1.8.3 mp4-file

This resource returns the same mp4 stream as the above, but when called from within a browser, a “File Save As..’dialog box will appear asking the user where they would like to download the remote file to. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/mp4-file


https://en.wikipedia.org/wiki/MPEG-4_Part_14

Acme Documentation

1.8.4 mp4-file-info

This resource returns a JSON-formatted response containing a ‘fileSize’ key:value pair. The value of fileSize is zerountil the file creation is completed, at which point it is permanently the file size of the finished mp4 animation file.Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/mp4-file-info


{"fileSize": 114656}

1.8.5 anim.mp4

This alternative mp4 resource returns the mp4 of an animation order via a static web hosting directory. This is providedfor certain browsers which can be extremely particular about the data structures of streamed media data, and as a resultthe standard /mp4 resource above will not load on these browsers. Using this anim.mp4 resource instead serves as aworkaround for users wanting more broad browser support. One result of this file based support however is a muchshorter provided download time from ACME; anim.mp4 files are deleted from availability within 3 hours. Sinceall users are expected to attain their mp4s upon animation completion, this short time window is not known to be aproblem, and again the standard mp4 resource is available for much longer. Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/anim.mp4

1.9 new

/new

/new starts the creation process of a new animated code and returns a response containing the Order Number to beused for all subsequent queries about (and certain limited updates to) the started animation.

Example:

GET: https://api.acme.codes/new?msg=HelloQrScannersOfTheWorld!



Below are the optional arguments when calling the /new resource:

1.9.1 apiKey

First, it’s important to remember that sending a value for the apiKey argument is optional; we do this so any developercan learn, experiment with, and integrate the API at any time. See the SDK section of this documentation for workingexamples to be used by anyone. Of course, if no apiKey argument is supplied, the service will watermark the customportions of the animation and limit the embedded message to a demo page that proves the message can be put into thecode by our API, but limits any practical use of the code.

To generate animated codes without watermarking and without message demo wrapping, a valid API Key associatedwith a paid subscription to ACME.CODES must be subitted in this argument. Contact [email protected] to be givena temporary “try-it-out” API key or purchase a permanent API Key for completely unlocked codes.

1.9. new 29

https://en.wikipedia.org/wiki/Application_programming_interface_key

mailto:[email protected]

Acme Documentation

1.9.2 anim

The animation to be applied to the code. See anims-json and animation-list resources for a complete list ofvalid values for anim. Default = ‘Exchange’.

1.9.3 applyFrameNumbers

This setting allows for diagnostic per frame overlays of a frame hand and frame count to ensure altered animations arerendered correctly for expected total and block times.

1.9.4 bgpColor

Background Plate Color. Background color. Default = ‘FFFFFF’ (White). Multiple hex color values can be suppliedseparated by commas for multi color options. Green background example: https://api.acme.codes/new?bgpColor=00FF00

1.9.5 bitRate

Bitrate argument for encoding mp4 files. Defines the target bitrate for the mp4 streaming encoder. Default is 0; whenset to 0, allows the mp4 encoder to adjust the bitrate as can be best for the animation. When explicitly set, the higherthis number, the higher the quality of the delivered mp4 file, as well as the larger the mp4 file size. Example to createa higher than normal fidelity mp4 file: https://api.acme.codes/new?bitRate=1200

1.9.6 blocks

One of ACME’s most popular arguments for refining generated animations to preference. For any given animation,blocks= allows for arbitrary timing of the blocked portions of the animation. Each animation has default blocktiming; for example, the block timing of a code to image and back animation would be 2 seconds of the code, twoseconds animating to the image, 2 second hold of the image, and finally 2 second animation back to the code. (Note:the last two seconds are so ‘minus the last frame’ in order to support smooth looping transitions.) blocks= allowsfor overriding of any animation’s default block timing. So, say an animation is wanted that instead animates the codedisplay for one second, then animates to the image in 5 seconds, then holds the image for 2 seconds, then animatesback to the code in 3 seconds. With the block argument comma separated values representing the absolute times forblocks to start and stop, the needed argument would be blocks=0-1,1-6,6-8,8-11. All values are in seconds,not frames. Float values fully supported: 0-2.44,2.44-6 is ok. It is important to note some animations have onlyone block (Spin for example), while others usually have 4, and still others have overlapping animation block times.Default block values are given with the /anims-json resource. blocks values are also subjected to the lengthargument.

1.9.7 cdn

For paying subscribers only, this argument flags the request for animation files to be automatically uploaded to ourCloud Service Provider. Default value is 0. When set to 1/True, generated animation product files will be uploadedto a dynamically determined subdirectory of one of ACME’s CDN endpoint domains. See the CDN section of thisdocumentation for more details. Note this argument must be accompanied with an apiKey associated with a CDNsubscription account enabled by ACME.

For example, a subscriber who as paid for CDN services can call:

https://api.acme.codes/new?cdn=1&apiKey=<yourApiKeyHere>&gif=0&fbx=0&msg=helloFromAcme



Acme Documentation

which will generate a response with the additional information of the location of where the published animation fileswill be available after progress is 100:

{"orderNumber": "1576574190_8Z0U000D", "cdnMp4": "https://cdn.api.acme.codes/2019/12/17/e4983b0f-3688-48c1-a49a-f9345a5fb703/AcmeCode_283150.mp4"}

1.9.8 chromaRange

Supports the breadth of color range to be used in chromaKeys arg. Default value is 5.

1.9.9 fbx

Create fbx file. Default=True

1.9.10 fitFactor

This controls the fraction of the framed code which fills the camera view. If set to a low values close to 0, the codewill be very small in the frame, while if set to 1, the code will touch the borders. Note that some animations will alterthe default fitFactor to ensure all of the animation is properly viewable, but explicit setting of fitFactor will overrideanimation influences. Default is fitFactor=0.9

1.9.11 format

The desired format of the return value. Default = ‘JSON’. Usually format is left undeclared in order inherit thedefault ‘JSON’. However, two other options exist: ‘html’ and ‘png’. The ‘html’ option exists for people interatc-ing and learning about the ACME API with a browser, and will return an html web page containing a clickablelink to the final order products. This can be useful for interactive demonstration, testing, and verification of theAPI directly without relying on a more complex GUI front end. Without the ‘html’ option and without a frontend, the user is left to parse raw JSON and manually assemble the URL, which is not fun for anything but scripts.Also, there is the ‘png’ format option, which directly returns a png file format only if non-animated codes havebeen requested with anim=Still. See ‘Non-animated Codes’ for details. Examples: https://api.acme.codes/new?format=JSON (Default) https://api.acme.codes/new?format=html https://api.acme.codes/new?format=png&anim=Still

1.9.12 fps

Another one of ACME’s popular settings; Frames Per Second. All animations are defined in terms of time, so anyanimation can be rendered at any industry standard FPS while maintaining the same animation timing. The higherthe FPS, the higher the ‘look and feel’ of the smoothness of the animation. At the time of this document’s writing,the ACME default is 15FPS, but this will soon shift to 30FPS. Control over FPS can have significant effect over finalanimation file size, in particular gif files.

1.9.13 frameNumber

Limits the generation of the animation to one specific frame. Use of this is discouraged for normal use. Normal accessof individual frames should be through the /orders/[Order#]/frames/[n] resource. However, if the user is creating testsuites or similar use cases where it is known in advance that only one frame is needed, it can be helpful to use thisargument to optimize test execution time by limiting generated output to just one frame.

1.9. new 31

https://acme.readthedocs.io/en/latest/Non-animated%20Codes.html

Acme Documentation

1.9.14 frames

Create rendered frames file. Default=True. Required for most usage. By turning off, delivery times for fbx files isreduced, which is helpful for people wanting only digital 3d files.

1.9.15 gif

Create gif file. Default=True. Note gif generation requires the longest processing time of all other creation processes.

1.9.16 imageRotation

The rotation to be applied to a supplied image URL. Eample: https://api.acme.codes/new?anim=Spin&img1=https://www.acme.ink/demos/acmecodes/tImg/img1.png&imageRotation=90

1.9.17 img1

The image URL to be applied within the animation, if supported by the selected animation.

Example: https://api.acme.codes/new?anim=Spin&img1=https://www.acme.ink/demos/acmecodes/tImg/img1.png

Overview: there are two ways to supply an image to an ACME animation:

1. At initial order creation time, by supplying a URL to an image published on the internet via the img1= argumentfor the /new resource, an image can be inserted into an animation right from the start. The advantage here is the imagegoes in ‘all at once’ in one call. The disadvantage is the image must already exist over http/https and be published onthe internet before the call to /new is made.

2. Alternatively, a different call sequnce can be used. After the intial order has been created via a call to /new, a POSTof an image to the image resource will trigger the order animation to be refreshed after order upload is complete. Theadvantage is the image need never be published on the internet, while the disadvantage is that two seperate calls mustbe made to create the animation.

Also important are the supported file formats of the provided images. The API supports a wide rang of industrystandard file formats including PSD, GIF, JPEG, PNG, Targa, TIFF, XPM, ICO, SVG.

length

Length, in seconds, to constrain or expand the animation time length. So, if a default animation’s time is 4 seconds,using length=2 or length=10 can be used to customize and shorten or extend the length of the animation. Lengthis applied on top of - but still respecing the relative values of - the blocks argument. Think of of the lengthargument as stretching or shrinking any explicitly defined or default values of the block timing. Default value oflength is specific to each animation, and can be derived from the last value of the default blocks value in /anims-json.

1.9.18 mp4

Create mp4 file. Default=True


Acme Documentation

1.9.19 msg

The message to be encoded into the code. Default = ‘https://acme.codes’ https://api.acme.codes/new?msg=GreetingsCustomer!

1.9.20 multiSampleEnable

Also known in the industry as anti-aliasing, this setting improves the edge smoothness for high contrast bordersthat are at an angle. The ‘jaggies’, or staircase-like outline of simple renderings of angled edges are smoothed bysampling (measuring / calculating) multiple times the expected tonal within each pixel. Though this can slow downframe creation time, today’s hardward GPU powered rendering (including ACME’s default renderer), any slowdownis negligible per frame, but can add up to measurable amounts when multiplied over many frames to be rendered in ananimation. Default is on.

1.9.21 multiSampleCount

If multiSampleEnable is on, this setting controls the number of additional samples to be made per pixel. Defaultis 32, the highest available.

1.9.22 motionBlurEnable

Motion blur is one of the corenerstones of quality animations; if an object is moving quickly within a single frame,it needs to look blurry with the motion as would be expected by any image capturing device. Without motion blur,animations or video have an unnatural ‘crisp’, or ‘sharp’ feel. And, like most quality improving features, slows downcreation time substantially. Some cusomters prefer the crisp feel, so this setting allows for control of motion blur.Default is motionBlurEnable=True, though some animations default to disabling it without an explicit override.

1.9.23 motionBlurSampleCount

This controls the number of samples taking for applying motion blur per frame. Default ismotionBlurSampleCount=32

1.9.24 motionBlurShutterOpenFraction

This controls the fraction of a frame that the renderer’s virtual camera shutter is open. 0 = shutter is never open, while1 = shutter is open the entire frame. Default is motionBlurShutterOpenFraction=0.2

1.9.25 partner

Client identifier. Default = ‘demo’ Example: https://api.acme.codes/new?partner=RetainedAcmeClient

1.9.26 pictureFrame

For animations combining both a scannable code and a provided image, pictureFrame allows control over thescaling of the image or the code to be within the confines of the other. Specifically, if pictureFrame=code, thenthe image is scaled in the animation to be within the boundaries of the code. If pictureFrame=image, the code isscaled in the animation to be within the boundaries of the image. Default: pictureFrame=code.

1.9. new 33

https://acme.codes

Acme Documentation

1.9.27 pixelColor

The color of the base code tiles in hex. Default = '000000' (Black). Multiple hex color values can be sup-plied separated by commas for multi color options. Red pixel example: https://api.acme.codes/new?pixelColor=FF0000

1.9.28 pixelType

Shape of the pixels (or “tiles”) to use in QR codes. Valid set: [‘square’, ‘circle’] Default = square. https://api.acme.codes/new?pixelType=circle&xres=400&yres=400

Result:

1.9.29 random_seed

Many animations available to clients contain certain randomized elements in the final animations. Explicitly set-ting randomSeed allows for these randomized elements to be consistent for the client for any given code. Thisargument also allows for consistent results in our automated test systems. https://api.acme.codes/new?random_seed=5


Acme Documentation

1.9.30 remoteIp

Intermediary front-end web pages, apps, or automated API’s can send (and are sometimes required to send) the IPaddress of the remote client through this argument. https://api.acme.codes/new?remoteIp=123.456.789.1

1.9.31 createAnimation

Default: True. Used with Image call upload sequence. If a user is going to upload a custom image, the first call to/new would have createAnimation=0, which delays the animation creation until after the custom image is uploaded.

1.9.32 stencil

Stencil option; rather than create a positive pattern of dark tiles on a white background to form the code, create thenegative pattern of white tiles against a transparent background to form the code (complete with white border frame),like a stencil . This allows for a client to use the resulting animation as an overlay to a custom darker image, animation,or video. Care must be taken to ensure the code is still scannable in these conditions; since final scannability is onlydeterminable on the client side, scannability with this option is fully the responsibility of the client. Also, unlessand until the stencil version of the animated code is actually on top of a dark background, the initial delivery willbe functionally invisible when viewed against the white default of browser backgrounds. Default = false Example:https://api.acme.codes/new?stencil=true

1.9.33 transparentBackground

Removes the background plane and allows for full transparency. Note transparency is only supported in gif file formats.This argument is used in conjunction with the stencil argument, in some cases automatically.

1.9.34 transpTriggerValue

For animations supporting tile creation limited as a function of transparency in the image, this argument defines thevalue considered to be transparent. Default value is 0.

1.9.35 xres

X Resolution, or Pixel Width, of the generated animation. Note if this value is not in harmony with yres, cropping canoccur in the final product. Default = 150 https://api.acme.codes/new?xres=400

1.9.36 yres

Y Resolution, or Pixel Height, of the generated animation. Note if this value is not in harmony with xres, croppingcan occur in the final product. Default = 150 https://api.acme.codes/new?yres=400

1.10 orders

/orders/<*>

This resource is the root endpoint for all created orders. After any call to new - which returns an order number - theorder animation files can be found in /orders/<order_number>/<desired_filetype>

1.10. orders 35

https://en.wikipedia.org/wiki/Stencil

Acme Documentation

It is important to remember that all content in /orders is only available temporarily.

Subscribers wanting to keep their animation files must do at least one of two things:

1. Download and manage their files as they wish as they are created; older content in the /orders resourceis scrubbed daily for storage re-use. ACME only supports content availability in /orders for 3 days aftercreation.

2. Optionally, ACME customers can pay ACME additionally for CDN subscription. ACME provides for automateduploading of generated content to our CDN provider. See the CDN section of this documentaion for details.

Example URLs:

https://api.acme.codes/orders/1444979323_ODFAUQSE/mp4https://api.acme.codes/orders/1444979323_ODFAUQSE/gifhttps://api.acme.codes/orders/1444979323_ODFAUQSE/fbxhttps://api.acme.codes/orders/1444979323_ODFAUQSE/frames/3https://api.acme.codes/orders/1444979323_ODFAUQSE/zip (Limited availability)

1.11 image

/orders/<order number>/image

This resource is a Restul POST target for a remote client to upload an image to an existing order. After the image isreceieved by api.acme.codes, the order is automatically refreshed and begins processing anew as if the order was justcreated.

After posting to the image resource, it is recommended to check the progress resource iteratively for completion,since requests for mp4s immediately following a post to image will return 202 responses as the animation processtakes time to complete.

Reminder: this image resource is one of two ways to create an animation with a custom image. The two patterns ofanimation creation with custom images are:

1. The “Don’t use this image reousrce” way: First ensure the image is published on the web, then make a call tothe /new resource with the img1 argument set to the web address of the published image.

2. The “Use this image resource” way: Create the order with a call to /new first, then directly upload the imageto the order to this image resouce after the order has been created.

The advantage of the first pattern is that only one call to new must be made. The disadvantage of the first pattern isthat the image must be published via http/https on the internet.

The advantage of the second pattern is that the custom image does not need to be published on the internet in advanceof the call to /new. The disadvantage is that two calls to the api must be made to create the desired animation.

Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/image

Example return values:

(None, but <200> OK status code)

See the SDK section of this documentation for detailed working examples of POSTing to the image resource. Notethis is the only resource at api.acme.codes that requires a http/s POST; all other api calls can work through GETs. Thismakes most of the api easily explorable through a standard web browser.



https://restfulapi.net/http-status-202-accepted

Acme Documentation

1.12 progress

/orders/<order number>/progress

This resource returns a JSON-formatted response containing information key:value pairs about the specified ordersince the most recent edit.

“progress”: an integer in the range [0-100] which represents the percentage of completion for the most recentlyrequested animated code.

“stage”: a string description of the type of work currently being done to create the order. Example values include:

'Order Creation''Order Definition''Animation''Rendering''Watermarking''Gif Creation''Mp4 Creation''Internal File Verification''External File Verification''Order Complete'

“queue”: an integer of the count of unstarted orders currently in the request queue. If queue is non-zero, the systemis at maximum capacity and progress speed will be delayed. If queue is non-zero, most front end client systemscommunicate this information to users to help assure them as to why processing is slower than usual.

“mp4”: This field is only present when “progress” is 100. It is an explicit URL to the specific name of the mostrecently generated mp4 file (including any recent order changes) for display or download.

Example URL:

https://api.acme.codes/orders/1444979323_ODFAUQSE/progress

Example return values:

{"queue": 10, "progress": 0, "stage": "Order Creation"}{"queue": 0, "progress": 0, "stage": "Order Creation"}{"queue": 0, "progress": 15, "stage": "Animation"}{"queue": 0, "progress": 55, "stage": "Rendering"}{"queue": 0, "progress": 100, "stage": "Order Complete", "mp4", "https://api.acme.→˓codes/orders/1595107770_1EGWU128/AcmeCode_441535.mp4"}

1.13 thumbnails

https://service.acme.codes/anims/<anim>/thumbnails/anim.*

This resource returns a thumbnail-sized animated gif or mp4 which can aid user’s selection from a large animation list.Note thumbnails are hosted out of the service.acme.codes domain, not api.acme.codes. Example URL for gif:

https://service.acme.codes/anims/Spin/thumbnails/anim.gif


Example URL for mp4:

1.12. progress 37

Acme Documentation

https://service.acme.codes/anims/Spin/thumbnails/anim.mp4


Single frame image thumbnails have been temporarily removed.

1.14 version

version

This resource returns a JSON-formatted response containing software build and date information about this service.

{"buildNumber": 1747, "buildTime": "Tue Oct 20 22:14:11 2015", "version": "0.5",→˓"branch": "master"}


https://api.acme.codes/version


https://api.acme.codes/version

CHAPTER 2

Indices and tables

• genindex

• search

39

Documents

Acme Documentation - Read the Docs · ACME service would then return an animated requested ﬁle type. Depending on creation arguments described in this documentation, a ﬁle similar