NOTE! THIS IS A PRELIMINARY (BETA) RELEASE!

Which means- the documentation in this guide is partially updated.

And components probably still have bugs. And their inputs/outputs
may change which is always frustrating when you try to open an older
Grasshopper script and the component signatures no longer match.
But they are close to final and they definitely work on the example files
included. With all that in mind, you are welcome to take this early
opportunity to try them out!

Heliotrope

Finally, because this is an Beta release. please send thoughs, suggestions

and any examples of you would like to share to:
heliotrope@slateshinglestudio.com.

Solar Geometry
for Rhino & Grasshopper

2013 Slate Shingle Studio | All Rights Reserved | 1016 SW Clay St | Portland OR | 97201

User Guide
Version 2.0 BETA

Heliotrope License Agreement: Important!

By installing and using Heliotrope you a agreeing to an End User License Agreement (EULA) based upon the
Creative Commons Attribution-NoDerivs 3.0 License which may be found here:
http://creativecommons.org/licenses/by-nd/3.0/
In essence, Heliotrope is free to for commercial and non-commercial use, however, you must include attribution
for any project it has been used in. Heliotrope is not an open-source project. No permission is granted to
decompile, analyze or modify the source code in any way. For details, contact heliotrope@slateshinglestudio.com.

Installation
To install Heliotrope, simply drag and drop the .gha file onto the Grasshopper desktop. Enough said. If
Grasshopper reports that an earlier version exists overwite it.

Heliotrope User Guide

Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

1. Introduction
Heliotrope provides a suite of geometric solar analysis tools for the Rhino/Grasshopper programming
environment. It includes components to calculate solar vectors and projected geometry for dates, times, and
locations all parametrically controlled by the Grasshopper programming model. Heliotrope is highly accurate,
geometrically precise, and because it uses geometric analysis instead of animations of single point tests, it is fast
and highly usable as an interactive design tool. Use Heliotrope to quickly understand and manipulate alternative
design compositions against multiple solar vectors, to parametrically construct geometry based upon solar paths
across days and seasons, or to create interactive geometry that changes according to the suns position in the sky.
The solar vectors and geometry of Heliotrope may also be integrated with other Grasshopper components, such as
Firefly, to control Arduino microcontrollers using solar positions.

1.1. Example usage

The simple example above generates and displays the solar arc for a single date and a solar vector for a time on that
date, with both date and time parametrically controlled by the model. The program elements are clustered into the
following steps:
1) Compose a Julian Day value for the date of interest using a series of integer inputs for year, month, day,
hour, minute, second and a double value input for time zone offset in hours. Further examples
illustrate the use of sliders or control knobs to actively change the desired solar position.
2) Provide the current location of the model using double values for latitude, longitude (specified in degrees)

Heliotrope User Guide

Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

and direction of north (specified with a vector input).

3) If using Rhino 5, the date, time and location specified in the Grasshopper model can also be used to drive
the Rhino models Sun Panel using a RhinoSet component. It is also possible to use the Rhino5
Sun Panel as an input to the Grasshopper through a RhinoGet component included in Heliotrope.
4) In Group 4, Heliotropes Solar Day Events component generates a unit radius solar arc centered on the
world-XYZ origin using the desired date and location information as input. The arc is scaled appropriately for viewing.
5) In Group 5, Heliotropes Solar Calculator component generates the specific solar vector for the specific
date, time and location. This vector is scaled to match the solar arc radius and a small sphere
placed on then end of the vector to help visualize the suns position.
The Rhino screenshot below shows the example output. The solar arc and sun sphere appear in red; North as a
black arrow; and the solar vector in orange.

Heliotrope User Guide

Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

2. A few up front details

2.1. Julian Day values: date and time data type
Heliotrope uses Julian Day values, a standardized value used in astronomical calculations, to represent dates
and times. Julian Days are real valued numbers, with the integer part identifying a specific day and the real
part a fractional portion of the day between 12:00 am and 12:00 p.m. For the most part, users see Julian Days
represented as normal date and time strings, the numeric part is kept under the covers. The Julian Day data type is
designed to be easy for users to convert to and from standard string formats and as well as double values useful for
mathematical manipulation.

2.1.1. Julian Day data type and time zones

There are no time zones in Julian Days. All have a Universal Time Code (UTC) offset of 00:00 (hours and minutes).
For convenience, the Heliotrope components that compose or expand Julian Day values have an additional
Offset input in hours, to convert to and from local time.

2.1.2. Julian Day data type and string values

Julian Day data types convert to and from strings in standard date string format:
(MM/DD/YYYY hh:mm:ss (+/-)hh:ss)
where:
MM/DD/YYYY: common era date in integer month, day and year values (order may vary according to your
computers cultural settings).
hh:mm:ss: time of day in hours, minutes and seconds.
(+/-)hh:ss: optional time zone offset from UTC-0 in hours and seconds.
Note the time zone offset. When a Julian Day is converted into a string, the offset will always be +00:00 because
Julian Day values are always relative to UTC-0. When a string value is cast to a Julian Day value, the time zone
offset is correctly factored in.

2.1.3. Julian Day data type and double values

The Julian Day data type also casts to and from double values when passed to standard Grasshopper math
components. Julian Day values converted to and from doubles use a base date of 1/1/2000 00:00:00. (The correct
base date used in astronomical calculations is actually January 1 of the year 4712 BCE. The number of digits
accuracy, however, needed to represent such a large number of days, hours, minutes and seconds offset from that
date, is slightly beyond the limits of accuracy for a double valued number.) Thus, in Heliotrope the Julian Day
value for 1/1/2000 00:00:00 converts to a double value of 0.0. Noon on that date is represented by a double value
of 0.5. Similarly, Midnight on January 2nd, 1/2/2000 00:00:00, converts to a double value of 1.0, and noon to 1.5.
Through the use of standard Grasshopper sliders, it is possible to create Julian Day values over ranges of periods
during minutes, hours, days or even years. Some of the example programs provided with Heliotrope illustrate this
capability by using a 0.0-1.0 slider to move across a single days times from sunrise to sunset.

2.2. Solar Arcs and Celestial Spheres

Heliotrope uses a vector-based geometric approach to solar calculations and creates Rhino geometry objects
used for visualization and design manipulation. In particular, the solar arcs and associated celestial sphere scale
arbitrarily around the point of projection. The Heliotrope components create unit scale objects which may then be
transformed to arbitrary size and location. If your solar arcs are not the right size, scale them!

Heliotrope User Guide

Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

2.3. Exchanging data with the Rhino model

Heliotrope provides two components to exchange data with the sun system used in the Rhino 5.0. Beta release.
RhinoGet gets the date, time, latitude, longitude and north vector and time zone offset settings from the Rhino
model and updates in real time as changes are made the Rhino model settings. RhinoSet sends the same data
back to the model with the exception of the time zone. (At the time of this release, the time zone setting of the
Rhino model is not accessible through the Rhino API. RhinoGet calculates the appropriate time zone value by
computing the difference between the models local and UTC:0 times. There is no mechanism, however, for setting
the Rhino models time zone from Heliotrope.)

Heliotrope User Guide

Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

3. The Components
Heliotrope 2.0 provides 22 components under the Heliotrope tab on the Grasshopper ribbon broken into 5
groups.
Sun: Calculators for solar position
Shade: Calculators for solar shadow studies
Julian Day: Components for mathematical manipulation of Julian Day values
Rhino: Components for accessing and driving the sun settings on the Rhino model
Util: Utility components useful in solar studies

3.1. The Sun Group

These components are the brains of the Heliotrope package. For given Julian Day input values they calculate solar
vectors and solar day arcs.
Solar Calculator: Calculate solar azimuth and elevation. Provide the results in degrees and
the solar vector pointing towards the suns position.

Inputs:

JDay: Date and time value expressing represented as a JDay data type, a double value,
or a date and time string (defaults to 1/1/2000 00:00:00)
Lat: Latitude in degrees as double; -90...+90; + to north of equator (defaults to 0.0)
Lon: Longitude in degrees as double; -180...+180; + to east of Greenwich (defaults to
0.0)
N:
North vector (defaults to y-axis)

Outputs:

A:
E:
SV:

Sunset

Azimuth angle, in degrees as double, clockwise from north in the xy-plane.

Elevation angle, in degrees as double, up from xy-plane along the azimuth
angle.
Solar vector as a vector data type.

Solar Noon

Sunrise

Sunrise, Solar Noon and Sunset: Each of these modules calculates the solar vector
and time of the respective event. Input values are identical to those used by the general
Solar Calculator component, however, only the date portion of the input JDay value is
used to identify the date of calculation.

Inputs: See Solar Calculator above.

Outputs:

Rise, Noon, Set: Julian Day value of the time of respective solar events.
All other output values: same as Solar Calculator above.

Heliotrope User Guide

Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

Solar Day Events: This component calculates Sunrise, Sunset and Solar noon times and
the solar arc through the three events.

Inputs: See Solar Calculator above.

Outputs:

Rise, Noon, Set: Julian Day value of the time of respective solar events.
Arc: Unit scale Rhino arc curve representing the solar path on the date.

Solar Arc: This component provides a one-stop shop for calculating a solar arc and moving
a sphere representing the sun along it.
Inputs:
JDay: Date and time value expressing represented as a JDay data type, a double
value, or a date and time string (defaults to 1/1/2000 00:00:00)
Lat: Latitude in degrees as double; -90...+90; + to north of equator (defaults to 0.0)
Lon: Longitude in degrees as double; -180...+180; + to east of Greenwich (defaults
to 0.0)
N:
North vector (defaults to y-axis)
O:
Origin, centerpoint at which to locate the arc (defaults to world XYZ origin)
SA: Scale Arc, floating point value by which to scale the initially unit sized arc
(defaults to 1.0)
SS: Scale Sun, floating point value by which to increase or decrease the sphere
representing the sun
Off: Offset, a floating point value from 0.0-1.0 to place the sun between sunrise
and sunset along the arc (defaults to 0.5)
Outputs:
Arc: The arc representing the solar path
Sun: A sphere representing the sun and placed at the offset location between sunrise and sunset.
Vec: Vector pointing to the suns offset location
TimeOfDay: Calculated JDay value offset between sunrise and sunset

When: Using a high speed search algorithm (patent pending) calculate the two dates within
a given year when the sun will appear aligned with the given target vector.
Inputs:
Y:
Integer Year value in which to calculate closest solar dates.
Lat: Latitude in degrees as double; -90...+90; + to north of equator (defaults to 0.0)
Lon: Longitude in degrees as double; -180...+180; + to east of Greenwich (defaults
to 0.0)
N:
North vector (defaults to y-axis)
T:
Target vector along which to calculate closest solar position
Outputs:
Arcs: Solar Arcs on the calculated dates
Vecs: Calculated closest solar vectors
JDays:Calculated Julian Day values for the closest solar alignments
Heliotrope User Guide
Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

Cast: Project the shadow of a Brep object onto opposite to the direction of the solar vector
onto a planar surface. For convenience this component uses solar vectors as inputs, which
point towards the suns location rather than the direction of the shadow
the solar vector is
opposite to the direction in which the shadow will be cast.

Inputs:

B:
SV:
P:

Outputs:
P:
F:

Brep object to be projected

Solar vector defining the suns position
Receiving plane on which to create the projection
Projected Brep on the plane surface
Front: Boolean value set true if the projection falls on the front of the plane
(from the planes positive z-direction)

3.2. The Julian Day Group

If the solar calculators are the Heliotropes brains, the Julian Day components are its heart. These tools are

designed to provide the ability to parametrically manipulate dates and times in Grasshopper and control the
activity of the solar calculators.

3.2.1. Components for Julian Day composition, expansion, and type conversion
These three components provide mechanisms to compose Julian Day values from calendar dates, expand a value
into calendar dates, and simply store a JDay parameter value.
JDay:Parameter: Holds a single JDay value. Can be useful in converting date/time
strings or double values into JDay data values.

Input:

Date and time value expressing represented as a JDay data type, a double value, or a
date and time string (defaults to 1/1/2000 00:00:00)

Output:

Julian Day value as a Julian Day data type.

JDay: Compose: Compose a Julian Day output value as a JDay data type from a set of
calendar inputs.

Inputs:

Y:
M:
D:
h:
m:
s:
Off:

Year as integer, relative to year 0 current era (defaults to 2000)

Month as integer, [1 12] (defaults to 1)
Day of month as integer, must be a legal day within the specified month (defaults to 1)
Hour of day as integer [023] (defaults to 0)
minute of the hour as integer [059] (defaults to 0)
seconds of the minute as integer [059] (defaults to 0)
Time zone offset as real value in hours (defaults to 0.0)

Output:

JDay: Julian Day value as a Julian Day data type.

Heliotrope User Guide

Release 2.0 BETA

Copyright Slate Shingle Studio 2013

All Rights Reserved

JDay: Expand: Expand a Julian Day values represented as a JDay data type into its
calendar components, applying an additional time zone offset if provided.

Inputs:

JDay: Date and time value expressing represented as a JDay data type, a double
value, or a date and time string (defaults to 1/1/2000 00:00:00)
Off: Time zone offset as double value in hours (defaults to 0.0)

Outputs:

Y, M, D, h, m, s: Same calendar date and time values as in the

Julian Day: Compose component above. Date and time are in the local
time zone as defined by the Off input.
Str: Local time output in standard string format. Note that where the JDay input
will always end with a +00:00 hour offset, the Str output will end with the
hour offset values specified by the Off input.

JDay:Now: Current computer date and time value.

Input:

U:

Update date and time on each Grasshopper solution if this boolean input is true
(default to true)

Output:

JDay: Julian Day value as a Julian Day data type.

Heliotrope User Guide

Release 2.0 BETA

10

Copyright Slate Shingle Studio 2013

All Rights Reserved

3.2.2. Components for adding calendar values to Julian Days

In addition to composing Julian Day values, it is often desirable to add calendar periods to values. Unfortunately,
the relatively complex logic of calendar dates does not directly mesh with its JDay representation as a floating point
number. How many days should be added to add a year to a particular date? Depends on whether you are in a
leap year or not. How many days until the next month? Depends on the month you are in and whether or not you
are in a leap year or not.
There are issues of convenience to be considered as well. If I wish to add an hour to a JDay value, it is necessary
to supply a constant value 1/24. A minute requires the constant 1/(24*60). Simple enough to implement once but
cumbersome and time consuming to do repeatedly.
The next two components provide mechanisms to add calendar date and time periods to JDay base values while
avoiding potential logical inconsistencies resulting from differing numbers of days in months or years. These
components are particularly helpful when driven by Grasshopper Control Knob or Number Slider controls.

JDay:Add: Add additional real valued number of days, hours, minutes or seconds to a
base JDay value. As with the JDay:Add Years component, sliders or control knobs may be
used to drive the inputs, cycling through date and time periods at will.

Inputs:

JDay: Base date and time value expressing represented as a JDay data type, a double
value, or a date and time string (defaults to 1/1/2000 00:00:00)
+D: Real valued number of days to add (defaults to 0.0)
+h: Real valued number of hours to add (defaults to 0.0)
+m: Real valued number of minutes to add (defaults to 0.0)
+s:
Real valued number of seconds to add (defaults to 0.0)

Outputs

JDay: Resulting Julian Day value as a Julian Day data type.

JDay:Add Years: Add a double valued number of years to January 1st of the integer base
year. A slider producing a double value between [0.0 1.0] may be coupled with the +Y
input to move through all of the dates in a specific year. Similarly, a Control Knob with
a dial range of [0.0 1.0] and the knob limit restriction turned off attached to same
+Y input will advance by one year each rotation of the knob.

Inputs:

Y:
+Y:

Base year value as an integer offset from 0 Current Era (defaults to 2000)
Floating point number of years to add or subtract from the base year (defaults
to 0.0)

Output:

JDay: Julian Day value as a Julian Day data type.

Heliotrope User Guide

Release 2.0 BETA

11

Copyright Slate Shingle Studio 2013

All Rights Reserved

3.3. The Rhino Group

Rhino 5.0 implements a new sun system used to set information about a models global location, north orientation,
and a current date and time value. The following two components interact with the model systems to get or set
values from the model.

RhinoGet: Retrieve location and date/time settings from the Rhino model.

Inputs:

No Grasshopper inputs, however, the component is dynamically linked to the Rhino

Sun interface panel and will update (triggering the Grasshopper solver)
whenever the settings in the Rhino model change.

Outputs:

JDay:
Lat:
Lon:
N:
Off:

Rhino model date and time as a JDay value

Rhino model latitude setting in degrees as a double value
Rhino model longitude setting in degrees as a double value
North vector
Time zone offset in hours as a double value

RhinoSet: Set the Rhino model location and date/time settings. Only the actively
connected inputs are used to drive the Rhino model. Unconnected inputs are ignored.

Inputs:

JDay: Date and time value expressing represented as a JDay data type, a double
value, or a date and time string
Lat: Latitude in degrees as double; -90...+90; + to north of equator
Lon: Longitude in degrees as double; -180...+180; + to east of Greenwich
N:
North vector

Currently the Rhino API does not provide a mechanism for setting the models time zone.
As a result, no offset parameter is provided for here. This is represents no real difficulty,
however, as the models date, time and location are correctly set using UTC-0 values. The
position of the sun in the Rhino model will be correct, only the local time value will be out
of step.

Heliotrope User Guide

Release 2.0 BETA

12

Copyright Slate Shingle Studio 2013

All Rights Reserved

3.4. The Util Group

The components in the Util group provide miscellaneous additional support functions useful in solar design.

Compass Label: Generates a string label based on the compass direction of the input
vector.

Inputs:

N:
V:

Outputs:
L:

North orientation in World-XY plane.

Directional vector from which label is generated.
String translation of directional vector into compass label, ie, N, NW, NNW,
etc.

Trim: Really trim a trimmed Brep face. In certain instances applying a matrix to a Brep
trimmed Brep face Grasshopper results in the matrix covering the full, untrimmed
face rather than the trimmed one as expected. This component calls the necessary
Rhinocommon function under the covers to finish the trim operation.

Inputs:

UnTrm: The input face to be trimmed

Outputs:

Trm: The resulting trimmed face

Reflect: Reflect a vector off of a surface at an incident point. Extracts the normal vector at
the point of reflection and bounces the incoming vector accordingly.

Inputs:

S: Surface
P:
Point at which to reflect
V:
Vector to reflect

Outputs:
R:

Heliotrope User Guide

Release 2.0 BETA

Resulting reflected vector

13

Copyright Slate Shingle Studio 2013

All Rights Reserved

4. Example Programs
4.1. Disk objects oriented on the solar vector
In this example, developed by Nancy Cheng of the University of Oregon, a matrix of cone shaped objects is
oriented towards the solar vector at a given date and time.

The Heliotrope program is very similar to the simple solar arc example given at the beginning of this user guide.
The component groups perform as follows:
1) Using explicit values for year, months and day, define three dates, the winter solstice, summer solstice, and
fall equinox. In addition a slider, labeled season, is provided to select one the three dates.
2) Provide the current location of the model by providing double values in degrees for latitude, longitude and
a vector for the direction of north.
3) Using the Solar Day Events component, generate an arc for the three dates of interest. Compute the
difference between sunrise and sunset using the Julian Day values. Multiply that difference by a
slider input value between 0.0 and 1.0, creating a time value beginning at sunrise when the slider is
0.0, sunset when at 1.0 and proportionally through the day for values in between. Add the time of
day back onto sunrise to finish calculating Julian Day values across the times between sunrise and
sunset.
4) Using the Solar Calculator component, determine the solar vector at the exact time selected with the
Heliotrope User Guide
Release 2.0 BETA

14

Copyright Slate Shingle Studio 2013

All Rights Reserved

slider in step 3. Scale the vector and solar arc (also from Step 3) to a desired size. Display both
along with a globe placed at the end of the vector on the arc indicating the suns position.
5) Set up a series of parametric values controlling the matrix geometry to be generated.
6) Create the background matrix of panels and cut openings in which the rotating cones will rest.
7) Create the solar cone elements and orient them in the direction of the solar vector.
The output of the Heliotrope program generates the following geometry in Rhino:

To exercise the program, adjust the season slider to select one of the three solar arcs and the 0-1 day slider to move
the sun across the sky between sunrise and sunset on the selected date.

Heliotrope User Guide

Release 2.0 BETA

15

Copyright Slate Shingle Studio 2013

All Rights Reserved

4.2. Shadow Study Example

In this final example, the Cast component is used to project the shadow of a simple block object onto the worldXYZ plane.

The component groups perform as follows:

1) Using a slider and a JDay:AddYears component, move across the dates within a base year value set to
2012. The resulting Julian Day value is displayed as a string in the yellow panel component.
2) Read the model location latitude, longitude, north vector, and time zone offset from the Rhino model.
3) Given a base day derived from the slider in Group 1 and the sunrise and sunset values from the
Solar Day Events component, use a second slider to move across the times between sunrise
and sunset. The result of the sunrise-sunset computation is converted back into a local time value
string using a JDay:Expand component.
4) Display the solar arc from Group 3 scaled as desired.
5) Generate the solar vector for the specific time chosen in Group 3 using the Solar Calculator component.
Scale the vector to the size used in Group 4 and display in orange.
6) Create a simple box Brep object and cast it silhouette based upon the solar vector from Group 5.
To exercise the program, adjust the slider in Group 1 across days in the year and the slider in Group 2 across times
during each date. Observe the motion of the cast shadow as it moves with the suns position.

Heliotrope User Guide

Release 2.0 BETA

16

Copyright Slate Shingle Studio 2013

All Rights Reserved

The Rhino output:

Heliotrope User Guide

Release 2.0 BETA

17

Copyright Slate Shingle Studio 2013

All Rights Reserved

Acknowledgements
Research and development rarely happens in a vacuum. The author would particularly like to thank Professor
Nancy Cheng of the University of Oregon for her insightful thoughts and continual support of the R&D work
behind this project. Professor Chengs lovely origami shading devices have provided the perfect vehicle for driving
development of these tools.

I would also like to acknowledge the development team at Robert McNeel & Associates for their continual efforts
to make Rhino and Grasshopper the best geometric modeling program possible while also taking the time to
enable the incredibly innovative development community that surrounds it. Particular thanks to Scott Davidson,
Steve Baer, Dale Fuglier and of course David Rutten, although I know there are many others behind that front line
team.

Heliotrope User Guide

Release 2.0 BETA

18

Copyright Slate Shingle Studio 2013

All Rights Reserved

Appendix A: Heliotrope End User License Agreement

By installing and using Heliotrope you a agreeing to an End User License Agreement (EULA) based upon the
Creative Commons Attribution-NoDerivs 3.0 License which may be found here:
http://creativecommons.org/licenses/by-nd/3.0/
In essence, Heliotrope is free to for commercial and non-commercial use, however, you must include attribution
for any project it has been used in. Heliotrope is not an open-source project. No permission is granted to
decompile, analyze or modify the source code in any way. For details, contact heliotrope@slateshinglestudio.com.

Heliotrope User Guide

Release 2.0 BETA

19

Copyright Slate Shingle Studio 2013

All Rights Reserved