Message Boards

GROUPS:

Staff Picks Data Science Recreation Visual Arts Graphics and Visualization Interface Construction Wolfram Language Wolfram Cloud Data Drop Know-How

Silvia Hao

How to make a Christmas card on the cloud

Silvia Hao, CTO at Glimscape Technology

Posted 1 year ago

6399 Views

7 Replies

17 Total Likes

Follow this post

POSTCARD: https://www.wolframcloud.com/env/silviah/Published/xmas.html

Recently I made a Christmas card as a practice on how to use various Wolfram technologies to develop a website. As people are giving positive feedback on it, I think it would be nice to share my experience here.

The whole project involves 4 main parts:

◼

Static resources hosted on Wolfram Cloud;

◼

APIFunction-s deployed on Wolfram Cloud;

◼

Databin as persistent data storage;

◼

3D models generated offline in the desktop version of Mathematica.

I'm going to talk about the first 3 parts in this post, and a separate post for the 4th part as it's relatively unrelated to the cloud stack.

When finished, the whole project consists of 4 static files on the cloud:

xmas/ spikey.json stem.json leaves.json xmas.html

3 public web APIs:

https://www.wolframcloud.com/obj/.../snowflake
https://www.wolframcloud.com/obj/.../getDecor
https://www.wolframcloud.com/obj/.../submitDecor

and 1 private Databin called “Christmas Present Store”.

The whole design

In this project, we will make a single page website. When a browser visits this website, it will query our server, ask for five PNG images for the snow scene, and three 3D models for the Christmas tree scene. Those resources will be used by scripts in the webpage.

By design, there are two API interactions between the webpage and the server, and one API interaction solely on the server-side.

◼

When the cover page is clicked, the card will open, a query to the getDecor API will be made. When succeed, the server will query a persistent storage separately hosted on the cloud (i.e. the private Databin “Christmas Present Store”), generate 3D models of some polyhedrons according to the query result and use that as getDecor’s response. It will then be processed on the client-side. Finally, the polyhedrons will be put in the tree scene.

◼

When any of the present boxes under the tree is clicked, a query to the submitDecor API will be made. When succeed, the server itself will call the genDecor API, which will randomly generate a polyhedron and add it to “Christmas Present Store”. Finally submitDecor will ask “Christmas Present Store” for some latest added polyhedrons and generate 3D models of them as response to the client. The response will then be processed and rendered on the client-side.

Utilities

As usual, here is the code dump of some helper functions. Readers can evaluate then safely skip this section.

code dump of helper functions

/16/19 21:07:42 In[1]:=

ClearAll[pipe,branch]pipe=RightComposition;branch=Through@*{##}&;

ClearAll[corssSectionProfile]corssSectionProfile=BSplineFunction2,{{0.,1.},{0.,1.}},{3,3},{False,False},

Control net

Head: List

Dimensions: {20,4,2}

Byte count: 8688

,Automatic,

knot vectors

Head: List

Length: 2

Byte count: 912

,{0,0},MachinePrecision,"Unevaluated";

Databin as persistent cloud storage

Datadrop service is designed to store a large number of small records. In our project, a private Databin will be used to store customer generated data, but will only be accessible by our own APIs.

CreateDatabin[<|"Name""Christmas Present Store",Permissions"Private"|>]

/29/19 21:46:18 Out[153]=

Note although Private permission is enough, we have made our “Christmas Present Store” partially public. Readers who are interested can read it freely through short ID “J0wpuKJu”, or from the following address:

◼

https://datadrop.wolframcloud.com/databin/DDae955165439-97c6-40f4-ae6a-6b1254fcd3b5

Serving static resources through the Wolfram Cloud

There are 2 kinds of static resources involved in our Christmas card project: 3 JSON files representing the 3D models of the Spikey and the Christmas tree (one for stem, one for leaves), and 1 HTML file for our one page website.

JSON

We will talk about the content of the JSON files in a separate post. To serve them from the cloud, we just need to upload them with a simple CloudExport command (refer to section Hosting APIs on the Wolfram Cloud » getDecor for the implementation detail of the metadataToModel function).

CloudExport<|"id""Spikey","WLcolor"

|>//pipe[metadataToModel@pipe[ScalingTransform[2{1,1,1}],TranslationTransform[{0,0,30}]],#〚{"vtx","color","mesh"}〛&],"JSON","xmas/spikey.json",Permissions"Public"

/22/19 21:36:45 Out[24]=

CloudObject[

https://www.wolframcloud.com/obj/user-ae9080e9-a3d2-4e3f-ad43-2cd6e62b0594/xmas/spikey.json

]

/29/19 12:50:02 In[65]:=

"https://www.wolframcloud.com/obj/user-ae9080e9-a3d2-4e3f-ad43-2cd6e62b0594/xmas/spikey.json"//URLRead//ImportString[#@"Body","RawJSON"]&//Dataset

This can be done similarly for the stem and leaves:

CloudExport

tree_leaves//Compress

Head: String

String length: 106598

Byte count: 106664

//Uncompress,"JSON","xmas/stem.json",Permissions"Public"

CloudExport

tree_leaves//Compress

Head: String

String length: 498990

Byte count: 499056

//Uncompress,"JSON","xmas/leaves.json",Permissions"Public"

HTML

For the HTML file, the simplest way is to upload it as raw HTML string:

CloudExport

xmas.html//Compress

Head: String

String length: 21334

Byte count: 22536

//Uncompress,"HTML","xmas.html",Permissions"Public"

For JavaScript libraries, they are either hosted on a third-party CDN or inlined within the HTML, so there is no need to serve them individually.

Serving dynamic resources through the Wolfram Cloud

In our webpage, there is also a dynamic resource, i.e. the snowflakes. Eagle-eyed readers might have noticed that when the webpage is refreshed, the shapes of the snowflakes will change. In fact, despite the snowy scene is adopted from THREE.js official sprite example, we made some change so that instead of using static PNG files for the snowflake images, the webpage will query an API defined as following, which will randomly generate a snowflake and return it as a proper PNG resource. The core of the API is adopted from Simon Woods' brilliant code.

Note how we combine HTTPResponse and APIFunction[...,“String”] to get a customized API result. Also note how we added “Headers”{{“Access-Control-Allow-Origin”,”*”}} to the header so the API can be called from a domain different from www.wolframcloud.com, which is needed if the webpage is hosted elsewhere, say, on a local developing web server.

crosssiteSnowflake=APIFunction{},FunctionHTTPResponseModule{n=5,layer=3,arm,radius,pts},pts=arm=Accumulate[Join[{{0,0.1}},RandomReal[{-1,1},{n,2}]]];arm=arm.Transpose[RotationMatrix[{arm〚-1〛,{0,1}}]];arm=Join[arm,Rest[Reverse[arm.{{-1,0},{0,1}}]]];arm.RotationMatrix

#1π

&/@Range[6]&/@Range[layer];radius=Norm/@Flatten[pts,2]//Max;pts=pts//RescalingTransform[radius{{-1,1},{-1,1}},{{-1,1},{-1,1}}];pts//pipe[Map@Polygon,Apply[RegionSymmetricDifference],Graphics[{GrayLevel[1,.9],#},PlotRange{{-1,1},{-1,1}},PlotRangePaddingScaled[.05],BackgroundNone]&,Rasterize[#,BackgroundNone,RasterSize63]&,ExportString[#,"PNG"]&],<|"ContentType""image/png","Headers"{{"Access-Control-Allow-Origin","*"}}|>,"String";

/23/19 01:25:16 In[168]:=

CloudDeploy[crosssiteSnowflake,"snowflake",Permissions"Public"]

A 101 tip: although every call to our API https://.../snowflake will get a random image, to actually get 5 different images in one page, we will need to get around the browser cache mechanism. One common way is to call it with an extra dummy parameter, say, .../snowflake?s=1 , .../snowflake?s=2 , etc.

Hosting APIs on the Wolfram Cloud

As we mentioned at the beginning, we will need to deploy 4 APIs.

genDecor

The genDecor API is designed to take an integer input

, choose

random samples from the built-in PolyhedronData, assign

random colors to them, and return an Association as the result.

/29/19 15:20:51 In[67]:=

ClearAll[generatePolySet]generatePolySet[num_Integer]:=Module[{clsSet,polySet},polySet=Table[Nest[PolyhedronData/*RandomChoice,"Classes",2],num];polySet//pipe[branch[Identity,pipe[Length,RandomColor[Hue[_,UniformDistribution[{.7,1}],UniformDistribution[{.7,1}]],#]&]],Transpose,Map[AssociationThread[StringSplit["id,WLcolor",","],#]&]]]

/29/19 15:21:04 In[70]:=

generatePolySet[3]//Dataset

/29/19 15:21:04 Out[70]=

/22/19 21:49:14 In[39]:=

ClearAll[genDecorFunc]genDecorFunc=APIFunction[{"num"Restricted["Integer",{1,40}]},generatePolySet[#num]&,"WDX"];

We can optionally deploy genDecorFunc as a stand-alone API, or just use it directly in any server-side code, as it won’t be called remotely.

/22/19 21:49:29 In[41]:=

genDecorFuncAPI=CloudDeploy[genDecorFunc,"genDecor",Permissions"Private"]

Submit 40 initial decorations to “Christmas Present Store”

In the following code we will locally generate 40 polyhedron decorations, located near the envelope surface (defined through corssSectionProfile) of the tree leaves, then add them to the “Christmas Present Store” through DatabinUpload.

Module[{num=40,mybin=Databin["J0wpuKJu"],positionSet,newDecorSet,fullDataSet},newDecorSet=generatePolySet[num];positionSet=Table[Join[corssSectionProfile[(*height*)

RandomReal[1]

,(*radius*)RandomReal[{.8,1}]]//Insert[0,2]//RotationTransform[RandomReal[2π],{0,0,1}]//AssociationThread[{"x","y","z"},#]&,0.2RandomReal[{-1,1},2]//AssociationThread[{"rx","ry"},#]&],num];fullDataSet={newDecorSet,positionSet}//MapThread@Function[{newDecor,position},Join[newDecor,<|"position"position|>]];DatabinUpload[mybin,fullDataSet]];

getDecor

The getDecor API is designed to take an integer input

, return

3D models with some extra meta-informations in the JSON format.

Because of the data structure design on the client-side, we will need to make sure the 3D models are composed with only triangles, so some post-process of the PolyhedronData will be needed.

/29/19 17:07:49 In[102]:=

ClearAll[polyhedronNormalize]polyhedronNormalize[tf_:Identity]:=pipe[MapAt[N/*tf,1],MapAt[pipe[Map@pipe[branch[pipe[Rest,Partition[#,2,1]&,Map[Curry[Prepend,2]],Apply@branch],First],Apply[Construct]],Apply@Join],{2,1}]]

/29/19 17:08:28 In[106]:=

ClearAll[polyhedronNameToData]polyhedronNameToData[tf_:Identity]:=pipe[PolyhedronData[#,"GraphicsComplex"]&,polyhedronNormalize[tf],branch[First,Last/*First]]

Besides the 3D models, we would also like to give informations on how to query the objects in Wolfram Language. Those informations are assigned to the “WL Code” key. They will eventually become the golden cursive message on the right side of inner page of the Christmas card.

/29/19 17:08:53 In[108]:=

ClearAll[metadataToModel]metadataToModel[tf_:Identity]:=Function[Join[#id//pipe["PolyhedronData",ToString[#,InputForm]&,StringReplace["\"PolyhedronData\"""PolyhedronData"],<|"WL Code"#|>&],#WLcolor//ColorConvert[#,"RGB"]&//pipe[Apply@List,<|"color"#|>&],#〚{"position"}〛,#id//pipe[polyhedronNameToData[tf],Map[Flatten],MapAt[#-1&,2],AssociationThread[{"vtx","mesh"},#]&]]]

We customize the return result of our API with HTTPResponse:

ClearAll[getDecorFunc]getDecorFunc=APIFunction[{"num"Restricted["Integer",{1,40}]},Function[Module[{mybin=Databin["J0wpuKJu"]},Databin[mybin,-Min[Information[mybin,"EntryCount"],#num]]//pipe[Get,#〚;;,"Data"〛&,Map[metadataToModel],ExportString[#,"RawJSON","Compact"0]&,HTTPResponse[#,<|"ContentType""application/json"|>]&]]],"String"];

/23/19 00:33:11 In[150]:=

getDecorAPI=CloudDeploy[getDecorFunc,"getDecor",Permissions"Public"]

Test the API:

/29/19 15:38:00 In[75]:=

URLExecute[getDecorAPI,{"num"3},"RawJSON"]//Dataset

submitDecor

As we already talked before, the submitDecor API will call genDecor to generate a random polyhedron, place it at an appropriate position and persist the information, then do what getDecor does by directly call it:

ClearAll[submitDecorFunc]submitDecorFunc=APIFunction[{"num"Restricted["Integer",{1,40}]},Function[Module[{mybin=Databin["J0wpuKJu"],position,newDecor,model,data},newDecor=genDecorFunc[<|"num"1|>]//First;position=Join[corssSectionProfile[(*height*)

RandomReal[1]

,(*radius*)RandomReal[{.8,1}]]//Insert[0,2]//RotationTransform[RandomReal[2π],{0,0,1}]//AssociationThread[{"x","y","z"},#]&,0.2RandomReal[{-1,1},2]//AssociationThread[{"rx","ry"},#]&];data=Join[newDecor,<|"position"position|>];DatabinAdd[mybin,data];getDecorFunc[<|"num"#num|>]]],"String"];

/23/19 00:38:39 In[161]:=

submitDecorAPI=CloudDeploy[submitDecorFunc,"submitDecor",Permissions"Public"]

Conclusion

As what we have shown in this post, developing and deploying server-side APIs and resources are extremely easy with Wolfram Language, Wolfram Cloud and Datadrop service. For this small festival project, most of the time I spent is on modeling the tree and writing the client-side scripts. So I hope readers have got a taste of how developing a website would be like using the Wolfram cloud stack. Next time, I would like to talk about how we model the tree (spoiler: it’s adopted from VFX HIVE’s "Model a Christmas tree in Houdini", but in a Wolfram Language style).

Credits

◼

Christmas card design - from Peter O'Shaughnessy

◼

Snowflake sprites - from THREE.js

◼

How to create animated snowfall? - from Simon Woods

◼

Model a Christmas tree in Houdini - from VFX HIVE

POSTED BY: Silvia Hao

Answer

7 Replies

Sort By:

Moderation Team

Moderation Team, WOLFRAM

Posted 1 year ago

- Congratulations! This post is now featured in our Staff Pick column as distinguished by a badge on your profile of a Featured Contributor! Thank you, keep it coming, and consider contributing your work to the The Notebook Archive!

POSTED BY: Moderation Team

Answer

Eleazar Johannian

Posted 1 year ago

Thanks for the demonstration Silvia!

POSTED BY: Eleazar Johannian

Answer

Hsiao-Ching Chen

Hsiao-Ching Chen, Wolfram

Posted 1 year ago

Really Cool! Thanks for sharing.

POSTED BY: Hsiao-Ching Chen

Answer

Silvia Hao

Silvia Hao, CTO at Glimscape Technology

Posted 1 year ago

Thanks! This is my first time to try hosting a web-app totally on top of Wolfram stack. I have to say the development experience is much smoother than I expected!

POSTED BY: Silvia Hao

Answer

Hsiao-Ching Chen

Hsiao-Ching Chen, Wolfram

Posted 1 year ago

Would you consider do something similar for upcoming Lunar New Year? I think that would very interesting too! :)

POSTED BY: Hsiao-Ching Chen

Answer

Silvia Hao

Silvia Hao, CTO at Glimscape Technology

Posted 1 year ago

Hi Hsiao-Ching, Thanks a lot for you suggestion, it's a great idea! Sadly I'm quite occupied during the Lunar New Year. But I shall surely look into it when I have time!