Solar Toolbox
(by asepulve)
Grasshopper tools realized for taking into account sunlight and solar energy as form generators in the architectural and urban design process.
Support Email

Solar Toolbox is a set of Grasshopper tools realized for taking into account sunlight and solar energy as form generators in the architectural and urban design process. The first available panel includes Solar Envelope Tools, a group of components to be used for generating solar envelopes. In the future additional panels will be available including, but not limited to, tools for building massing, building cluster and fenestration design, and various utilities.

Solar Toolbox plug-in for Grasshopper is realized by Abel Sepulveda Luque and Francesco De Luca at Tallinn University of Technology (TalTech), Department of Civil Engineering and Architecture. Solar Envelope Tools is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Solar Envelope Tools

Solar Envelope Tools (SET) is a planning tool to be used for determining the maximum size and height new structures cannot exceed to guarantee required direct solar access to neighboring building facades. SET is based on the method introduced by Ralph Knowles to generate solar envelopes presented in: Knowles, R.L. (1981). Sun Rhythm Form. MIT Press, Cambridge (MA), USA.

The core functionality of SET is the selection of quantity and quality of hours of sun light received by existing building windows in case it is permitted by the direct solar access ordinance to fulfill which the solar envelope is generated. The sun light hours selection allows designers and planners to opt for different solar envelope shape, mass and performance, all of them fulfilling the direct solar access ordinance requirement.

SET is realized using methods and workflows developed in research projects presented in:

- De Luca, F. and Voll, H. (2017). Computational method for variable objectives and context aware solar envelopes generation. In: M. Turrin et al. (eds.), Proceedings of 8th Symposium on Simulation for Architecture and Urban Design, SimAUD 2017, Toronto, Canada, 22-24 May 2017, pp. 335-342.  

- De Luca, F. and Dogan, T. (2019). A Novel Solar Envelope Method Based on Solar Ordinances for Urban Planning. Building Simulation: An International Journal, 12(5), pp. 817-834.‐019‐0561‐1

Solar Envelope Tools version 0.0.1 includes 6 components:

  • Solar envelope Tools info
  • Location Data Reader
  • Analysis Period
  • Sun Vectors Selector
  • Solar Envelope Generator
  • Sun Path Generator


Solar envelope Tools info

This component introduces and provides the references for Solar Envelope Tools


Location Data Reader

This component reads a weather file (.epw format) and gives relevant information about the location such as the Latitude (Latitude), Longitude (Longitude), UTC and hourly direct normal solar radiation (AnnualNSR) for the whole year.


Analysis Period

This component generates sun vectors and associated direct normal solar radiation, sun altitude and sun azimuth for daytime hours (sun light hours) and fraction of hours (time step) for single and multiple analysis periods.

The component calculates the sun vectors (SunVectors) for a given location (Latitudeitude, Longitudegitude, UTC), analysis period defined by start and end (StartMonth, StartDay, StartHour, EndMonth, EndDay, EndHour) and time step (TimeStep).  Month, day and time input must be defined as a list. in case of single analysis period only one item is used for the list. In case of multiple analysis period different list items are used.

- Example of a single analysis period (from 22th May 00:00 until 22th August 24:00):

StartMonth=[5] | StartDay=[22] | StartHour=[0]

EndMonth=[8] | EndDay=[22] | EndHour=[24]

- Example of two analysis periods of more than one day each (from 1st June at 10:15 until 5th June at 19:30 and from 20th September at 10:15 until 27th September at 19:30):

StartMonth=[6 9] | StartDay=[1 20] | StartHour=[10:15 10:15]  

EndMonth=[6 9] | EndDay=[5 27] | EndHour=[19:30 19:30]  

- Example of three analysis periods of one day each (13th March, 1th July, 10th October):

StartMonth=[3 7 10] | StartDay=[13 1 10] | StartHour=[0 0 0]  

EndMonth=[3 7 10] | EndDay=[13 1 10] | EndHour=[24 24 24]

Exact time can be indicated without minutes e.g. 22. For time input with minutes the sexagesimal method is used with colon between hours and minutes e.g. 22:15.


Sun Vectors Selector

This component allows designers to generate solar envelopes taking into account the context, a minimum solar altitude and a minimum dead angle (angle between window surface and sun light direction).

The core function of the component permits to use it for different direct solar access ordinances such as those that require a fixed start-and-end hour, those that require a quantity of hours and those that require a percentage of actual direct solar access hours during analysis period or periods.

The component permits as well to utilize one of five sorting methods in case the ordinance at issue gives the possibility to the designer to select among a number of sun light hours and time steps.


Solar Envelope Generator

This component generates the solar envelope using the filtered, sorted and selected sun vectors, the plot where new building which cannot exceed the solar envelope will be realized and the windows for which the required quantity of direct solar access hours must be guaranteed. (The method for the geometrical determination of solar envelope points is based on the solar envelope component of Ladybug Tools

Sun Path Generator

This component generates a 3D representation of the annual sunpath of the location including daytime sun path curves for the day 21 of each month and analemma curves for all daytime hours of the day 21 of each month.

The component generates as well Line geometries representing: all the sun positions/rays (hours and time step) during the analysis period (output AllSunRays); all the sun positions/rays (hours and time step) visible from a selected window or group of windows during the analysis period (output VisSunRaysW); the sun positions/rays (hours and time step) during the analysis period selected for the generation of the solar envelope (output SelSunRaysW).

The component allows for the visual comparison of all the sun positions/rays (hours and time step) during the analysis period with the visible sun positions/rays from the windows used for the generation of the solar envelope, and with the selected sun positions/rays on the basis of required quantity and sun light quality.   

Solar Envelope Tools is still in its development phase, hence use it “as is”. The solar envelope calculation is solid and reliable. Many tests have been done but the tools still could contain bugs (e.g. analemmas visualization in the sun path component). Comments and suggestions are very welcome. This first release and some following versions are written in Python. In the future all Solar Toolbox will be written in C# for speed improvements and stability.

To install Solar Envelope Tools download the zip file, extract the the 6 .ghuser files, unblock them right-clicking on the file selecting Properties and Unchecking the Block box, and copy them in the Grasshopper UserObject folder usually located in C:\Users\”USERNAME”\AppData\Roaming\Grasshopper\UserObjects.