<< We recently shared a JSON Objects video tutorial over at our YouTube channel! If you prefer video content to written one, make sure to check part 1 below. >>

Click here to check out part 2 of this JSON video tutorial!

What is a JSON Object?

Have you ever had problems managing large amounts of data in your Grasshopper definitions? Have you ever had so many parameters that the definitions get too complicated to understand? Do you need a clean way to communicate between ShapeDiver and your web application? All these issues and more can be solved with our ShapeDiver JSON components.

JSON Components of the ShapeDiver Plugin for Grasshopper

If you have any knowledge regarding web development, you probably know what JSON is and can skip this section. JSON stands for JavaScript Object Notation .It is a standard readable file format used primarily to transmit data between a server and a web application. JSON Objects are surrounded by curly braces “{ }” and are written in key/value pairs. Keys must be strings (text) and values must be valid JSON data types: string, number, another JSON object, array, boolean or null.

To learn more about the JSON file format visit:

https://www.w3schools.com/js/js_json_intro.asp.

With our JSON components in Grasshopper, you are able to access this data format and use the keys as parameters. Additionally, if you combine the power of a JSON file and the use of data trees, you can build flexible Grasshopper definitions and reuse them in a wide range of cases. This is a great way to become more efficient and optimize your workflows. Let’s go through each of the ShapeDiver JSON components and explore the concept deeper.

How do I define and create a JSON object?

There are infinite ways to organize JSON objects. This is something that you have to build and organize depending on your needs. It can be as simple as a list or attributes (keys) and values, or it can become very complex with nested JSON objects, arrays of JSON objects, arrays inside attributes, etc...

An array is a collection or list of data. It is surrounded by square braces "[]"

Typically, the JSON object will be created in a web application using Javascript. From there, the application can send the object to Grasshopper as a string (see next section). As a consequence, defining how the JSON objects will be organized is often a collaboration process. The web developer sending the data and the Grasshopper designer need to work together. The goal is to define the most convenient way to communicate.

Once the structure of the JSON objects is clearly defined, you can build some examples in order to use them as test inputs in Grasshopper. You could either write your own JSON string from scratch in a single text panel or use Grasshopper tools like the Concatenate component to organize the data.

Another option is to use our ShapeDiverJSONConstruct component which we will explain later in this blog post.

How can you receive and and process a JSON object in Grasshopper?

The simplest way is to use the ShapeDiverTextInput component. This component generates a string input on ShapeDiver. Once online, it will be possible to set the string using the ShapeDiver control widget or the API. In order to set a default text in the component in Grasshopper, double click on it and a dialogue will open where you can define the text and a limit for the amount of characters.

You must always provide a single line of text. If you have your JSON organised in different lines, you need to use a JSON minifier (https://www.cleancss.com/json-minify/).

ShapeDiverTextInput imports a string into the definition, and now this string needs to be parsed.

ShapeDiverJSONParse

When receiving data from a web server, the data is always a string (text). This is why JSON is such a useful format because it converts easily to a string without any loss of information. However, in order to easily access the information inside this string, it must be “parsed”. In other words, we need to convert it into a computer readable native JavaScript Object. This way, the data will be organized and easily accessible. ShapeDiverJSONParse is the equivalent to the JSON.parse() javascript function and does exactly what you need:

Now that we have our JSON string converted into a Javascript Object. How can you access the data? Simple: use the component…

ShapeDiverJSONAccess

With this component you can look for any value by using the given attribute name. Additionally, you can provide an index number if the attribute you want to access contains an array/list.

ShapeDiverJSONAccess pretty much reproduces the dot notation used in Javascript to access JSON objects.

If you have an array of JSON objects with the same attribute name you are looking for, you will get back a tree in which each branch references an object of the array.

By getting this data organized in a tree, it becomes easy and flexible to reuse all or part of your definition endlessly. To be more specific, let's look at the example of a box. If I want my definition to be able to create as many boxes as I need with different sizes and positions, I can simply create a JSON object that contains an array of objects with an attribute defining the size of the box, and another one defining the position.

In this example below, the JSON object called “boxes” is an array of 5 objects, each defining a box. The more objects are added to this JSON, the more boxes are created.

Additionally, in this simple definition I used another useful ShapeDiver component. It helped me make a direct conversion of the array of three numbers that is given in the “position” attribute into a point. This component is called…

ShapeDiverJSONConvert

This is a very convenient component if you want to convert your parsed JSON objects into common Grasshopper data types. The most basic conversion is the one we just did by giving an array of 3 numbers that are then turned into points.

However, you can send more complex JSON structures for several Grasshopper data types. The plugin supports colors, boxes, nurbs surfaces, nurbs curves, transformations and more... JSON representations of the more complex data types contain a “type” and a “data” attributes. For example, a color has “type”:“color” attribute and a “data” attribute which contains an array of 3 numbers (R,G,B values).

The “data” attribute is the one that can get very complex as you will need to provide more and more data as your geometry grows in complexity. See for example the box example below:

It contains a plane with its origin, X axis and Y axis and an array with three domains defining the size for each axis.

In the sample definition linked at the end of this article, you will find examples of JSON representations for several Grasshopper data types. You can also try sending data to the ShapeDiverJSONConstruct component (see next section) and look at the JSON objects they generate.

Personally, I like creating simple data structures in my JSON objects and make the complex geometries natively in Grasshopper. Using a JSON to create these complex geometries can get a bit messy and confusing but if you think this is your solution, go for it!

There is just one last component that we need to review...

ShapeDiverJSONConstruct

So far we have been trying to parse, access and convert our JSON object into Grasshopper readable formats. However, what if we want to do the opposite and convert Grasshopper data types into a JSON format? Why would this be useful anyways?

If you didn’t know, ShapeDiver can also output data from the model by using the ShapeDiverDataOutput component. One can access this data from any web application with our API and use it in many ways such as pricing calculations, materials lists, counting elements, etc. If the data structure is too complex, the best solution is to create your own JSON Object to use as your data output by using our ShapeDiverJSONConstruct.

This component has 3 inputs, an optional input for a previous JSON object that you have already built and you want to add data to, an input with the data you want to put inside the JSON, and the “AddressString” that is the name you will give to that piece of data so that you can easily find it later in your web app.

The data input allows almost any kind of Grasshopper data Type and will automatically organize the JSON by giving it a “type” attribute and a “data” attribute with the necessary information that builds such element. For example, if you input a line, the JSON convert will give as “type”:“line” and the “data” is an array of two arrays which contains the X, Y and Z values of the start and end points.

But of course you can also input as data simple numbers or strings.

Conclusion

If you are dealing with very complex data structures in Grasshopper, my advice is to start learning more about how JSON objects work and explore the possibilities by using our plugin. This data format and the use of data trees will create a very clean and understandable definition which will be more flexible and optimized than by using the regular Grasshopper Inputs. If you have any further questions, please go to our forum and stay tuned for future blog posts. Finally, as promised, this is the master file where you can play with all the concepts we discussed today.

<<Want to learn more ShapeDiver Basics? Check out these other great blog posts!>>