Creating a Render Object Activity

This section requires photographs, illustrations or screenshots.

Overview

Within our Getting Started Package, you will find a Template folder. We have provided a template for the configuration file, which is used by the CLIO interface to set up the activity. We also include a content drafting template created in Microsoft Word that can aid collaboration when creating activities as part of a development team.

Options

Object Configuration

These are configuration settings for the object displayed within the activity.

Property	Description	Expected Parameters	Examples
Object	The 3D object file we would like to display within the activity.	OBJ file
Title	The name of the object.	Plain Text
Description	A description about the object that is displayed when the user hits the information button.	Rich Text

Render Configuration

These are configuration settings for the way the object is rendered.

Property	Description	Expected Parameters	Examples
Restrict Camera	Use simplified controls for this object.  The camera will move relative to the user’s input, allowing them to see the front side of the object. Setting this option to true will override this object's Controls and AutoRotate options.	"true" or "false"
AutoRotate	A description about the object that is displayed when the user hits the information button. This option is ignored when the Restrict Camera option is set to true.	"true" or "false"
Background Color	A flat background color to display behind the object.	Hex or HTML color code
Object Color	The base color to use when rendering the object.  This color may be affected by the material type selected.	Hex or HTML color code
Scale	The default zoom on the object, or how large the object appears relative to the screen. Depending on the object’s configuration, users may still be able to rescale the object.	Integer, greater than 0. This setting is greatly depending on the individual object file you are trying to render.  This is because OBJ files can be saved with different default scales.
Material	The material to use to render this object.	"wireframe", "flat", "smooth", "shiny", "matte", "metallic", or "cartoon"

Rotation Configuration

These are configuration settings for the way the object is rotate.

Property	Description	Expected Parameters	Examples
X	Rotation around its origin point, along the X axis.	Integer, measured in radians.
Y	Rotation around its origin point, along the Y axis.	Integer, measured in radians.
Z	Rotation around its origin point, along the Z axis.	Integer, measured in radians.

Controls Configuration

These are configuration settings for the way the object can be manipulated by the user.

Property	Description	Expected Parameters	Examples
EnableRotate	Whether the user should be allowed to rotate the object. This option is ignored when the Restrict Camera option is set to true.	"true" or "false"
EnableZoom	Whether the user should be allowed to zoom in and out on the object. This option is ignored when the Restrict Camera option is set to true.	"true" or "false"
EnablePan	Whether the user should be allowed to move the object around the scene. This option is ignored when the Restrict Camera option is set to true.	"true" or "false"

Lighting Configuration

These are configuration settings for the way lighting is rendered around the object.

Property	Description	Expected Parameters	Examples
Ambient	Whether the ambient light should be enabled. This light globally illuminates the scene equally.	"true" or "false"
Fill	Whether the fill light should be enabled. This directional light helps fill in the shadows created by the key light.  This light mimics sunlight.	"true" or "false"
Key	Whether the key light should be enabled. The main directional light used to illuminate the object.  This light mimics sunlight.	"true" or "false"
Back	Whether the back light should be enabled. This directional light can be used to help distinguish the object from the background.  This light mimics sunlight.	"true" or "false"
Spot	Whether the spot light should be enabled. This highly directional light can be used to center an object.	"true" or "false"

Creating the Activity

Define the Activity

All CLIO activities, regardless of their Activity Type, contain many of the same configuration settings.  These are used to configure the screen and load the correct content.  By defining this information, we can begin to draft more specific activity content.  This information is included in both the drafting template and the coding template provided with each activity type.

Read More: Defining a CLIO Activity

Drafting the Content

Download the template.

Open the provided Content Template for drafting the 3D Render activity.  First, we must decide on the basic descriptive information for the activity, such as the title, description, preview image and theme.  This information is required because it is used by the CLIO interface to properly display the activity.

Next, we can start to write the content needed for the 3D Render activity type.  This activity type will display OBJ files by rendering them based on your configuration.  There are options to change the camera, user controls, lighting, appearance and transformations.

For this activity, we are required to provide an object file, our descriptive information for it, as well as how we would like to have it displayed.  Our title and description are used to provide context for the object, through the informational label in the bottom right of the screen and the informational pop-up.  

We can configure how our object render will appear, such as color and material, the background color we want to place it on and if it should automatically rotate.  Along with the appearance of the object, we can configure the lighting that we would like to use to illuminate the object.  Finally, we can choose the way we want users to be able to interact with the object.

This activity type can provide the user with more than one object they can view.  For this example, we want to display a total of two objects.  To do this, we can copy the template for Object 1 and create a duplicate.  To keep organized, we can rename this duplicate to Object 2.

For each object, we are required to have the location to the OBJ file we wish to render. We need to add a title for the object, as well as a rich text description that is shown when users click on the title plaque.  

Now that we’ve described our object, we can start to decide how it will appear on the screen.  First, we can need to choose a color for our object and for our background, which will be formatted as a hex color code, such as #FFFFFF.  We can also choose the style used for the object, which is meant to help emulate certain materials and affects the way lighting is rendered.  The last thing we need to configure for the appearance of the object is its lighting.  There are five available lights that can be used in different combinations to illuminate the object in different ways to produce different outcomes.

Finally, we can choose how we want the user to be able to interact with the object.  We can manually configure whether we want the user to be able to rotate, zoom and move the object, or we can decide to restrict the camera.  When we restrict the camera, it provides a simplified interface for interacting with the object, causing the object to show off different angles of the object by touching the screen.  This setting will only display the front of the object, but it is useful for computers with minimal processing power, like the Raspberry Pi.

Coding the Activity

Download the template.

Edit the template.

The next step will be to take the content that was created in the Content template and begin to migrate it into the Configuration template.  We will need to open the provided Configuration Template for drafting the 3D Render activity.  This can be done in a plain text editor, but for the purpose of this manual we will be using jsoneditoronline.org/.  

First, we will be duplicating the necessary fields to ensure that we can enter all of the data that we’ve spent time drafting.  In our previous example, we decided to use two objects for our activity, so we should start by making sure we have enough objects within the configuration file.

The first object in our activity is labeled as ‘1’, underneath the Content object.  If we click on the small box to the left of ‘1’, we can choose to duplicate it as many times as we need to create enough.

For our example, we would need to duplicate it once to have a total of two objects.  After this is done, we will need to rename the objects we just duplicated.  Currently, it will be named “1 (copy)”.  It is important that these keys be numeric and unique.  We will rename our duplicate to “2”.

We can now start filling out the empty fields for the objects we want to render.  Under the first object, named “1”, we have the same information we entered into our content draft.

We can now start filling out the empty fields for the objects we want to render.  Under the first object, named “1”, we have the same information we entered into our content draft.  First, we can put the relative location of the OBJ object file we want to render.  We can then enter the title for the object into “Title”, and the rich text description into “Description”.

We can now begin to configure how we want the object to appear and how users should be able to interact with it.  Let’s get started by opening the Configuration object and viewing the configuration options.

Using our draft, we can begin to copy over these configuration options.  If we want the object to horizontally rotate automatically, we can check “AutoRotate” to change it to true.  We can also enter our desired background color into “Background Color” and object color into “Object Color”.  Next, we can enter the material style we would like to use to render our object into “Material”.  We do not want to restrict the user controls and camera for our object, creating a more interactive experience, so we will uncheck “Restrict Camera” to change this setting to false.

We disabled “Restrict Camera”, so that means we need to configure which controls we would like to allow the users to have over the camera.  Let’s open the Controls object so we can configure the camera controls.

We want to keep all of these options set to true, which will allow the user to rotate the camera around the object, zoom the camera in and out, as well as move the object around with a mouse or multitouch screen.  Next, we can open the Lighting object to view the lightning configuration for this object.

Following the same selections we made in our draft, we can check and uncheck the appropriate fields to set them to true or false, as needed.  We wanted to use only ambient, back and spot lighting.  Because “Ambient” and “Spot” are already true, we only need to set “Back” to true.

Using the same technique, we can fill in the same information for the second object we would like to display.  Once you are finished, you can download the finished JSON file by clicking ‘Save’ and then ‘Save to Disk’.  This file can be copied to the Program’s @Activity folder, and the media can be copied to the Program’s @Media directory.