Ladybug Light Analysis
Contents
Introduction
Expected Time: 45 min
In this tutorial you will learn how to analyze the sunlight hours of a Rhino model. Using this analysis, you can change your design based on expected performance or optimize it using an algorithm. For this tutorial, you will first need to install Ladybug. A comprehensive explanation on how to do this can be found in the Ladybug installation guide.
To analyze a model in Rhino, you will need to take several steps:
- Gather online data about weather at a certain location;
- Extract this information from the weather file;
- Project the sunlight data on your created model;
- Visualize the result;
Finally you can change or optimize the model based on the result.
Download the example file
In this tutorial, we will explain you step-by-step how to create the Grasshopper model that calculates the information you need. However, you can also download the following file, which is actually the final result of this tutorial. If you really want to understand how the script works, it is recommended to build it yourself.
- Download the example file: Ladybug Sunlight Script
Remember to Credit the Author when using this script for your projects!
Importing the EPW data
In this first step, we will find the weather data we need to analyze our model. Add an LB EPWmap component to the Grasshopper canvas. This component will open a webbrowser for you with the data we need. Connect a boolean toggle to the input of the EPWmap component to open the correct website automatically.
- Add an LB EPWmap component to the canvas
- Connect a boolean toggle to the input
Double-click on the Boolean Toggle. You will now be directed to the EPW weather data website. Zoom in to the location you need weather data from. If the exact location is not available, try to find the closest one.
- Double click on the boolean toggle
- Find the location you need
Next, click on the city and "copy link to clipboard". Your browser will now copy a link to the right address to retrieve the weather data from.
- Copy the weather data to clipboard
If you are following the BK3OV3 course, please copy the Amsterdam EPW link.
Open your Grasshopper file again. Now we need to import the data. Add an LB Download Weather component to the canvas. Connect a panel to the _weather_url input and paste the link in this panel. Ladybug will now retrieve the weather data for us.
- Open Grasshopper again
- Add an LB Download Weather component to the canvas
- Connect a panel to the weather_url input
- Paste the link in the panel
Extract the EPW data
Although we have imported the weather, it is not visible or separated in parts yet. Connect an LB Import EPW component to the epw_file output.
- Connect an LB Import EPW component to the epw_file output
If you connect a panel to one of the outputs of the Import EPW component, you will see that Ladybug has extracted several types of information. Internally, the data contains 8760 values, which is exactly equal to the amount of hours in one measured year.
Creating a sunpath
Now we want to use the location to generate a sunpath around our model. Add an LB Sunpath component to the canvas and connect the location output to the location input.
- Add an LB Sunpath component to the canvas
- Connect the location output and input
First, we need to make sure that the true north of our model is correct. Connect a panel with a value in degrees that indicates the true north of your model.
- Connect a panel with the true north in degrees
If you are following the BK3OV3 course, please use the value 60 for the true north
Furthermore, we need to specify which months, days and hours should be calculated. There are two components that we can use for this purpose: LB calculate HOY (just one hour or minute) and LB Analysis Period (a longer period of the year). The second respectively, mostly used for architectural design.
- Add an LB Calculate HOY component to the canvas
- Add an LB Analysis Period component to the canvas
For this example, connect three Number Slider to specify 15:00, 21th of July.
- Connect three Number Sliders to the LB Calculate HOY component to specify one hour
- Connect the hoy output from the LB Calculate HOY component to the hoys_ input
Finally, we need to add two more parameters to the sunpath component. First, we need to specify the centerpoint. You can also leave this parameter empty, then the coordinate 0, 0, 0 will be used. Secondly, you need to define a scale for the sunpath. In our case, let's change it to two.
- If necessary change the center point of the sunpath, just connect a point parameter to the _center_pt_ input
- Define a scale for the sunpath by connecting a panel with a value to the _scale_ input
If you are following the BK3OV3 course, please change the _scale_ to 0.25.
Your sun path should now be visible in your Rhino viewport.
Projecting the sun data on the model
In this chapter, we will calculate the amount of sunlight on a grid in our model. Of course, you will first need to create a model in Rhino. In the right image you can see an example of a model, which is used in the BK3OV3 course of TU Delft. As you can see, our model has a perforated roof that will block the sun. It will be interesting to find out how much sun is blocked and which spot will get most light during the day.
Add an LB Direct Sun Hours component to the canvas. As the name already indicates, the model will only calculate direct sunlight.
- Add an LB Direct Sun Hours component to the canvas
- Connect the sun vectors output to the _vectors input
Since Ladybug sunlight calculations can take a while, it is better to connect a Boolean Toggle to the _run input. When this toggle is set to True. Grasshopper will start running the component.
- Connect a Boolean Toggle to the _run input
- Make sure the toggle is set to "False"
To make sure our model is not too complicated to calculate, we need to specify a grid size. You may need to check if your Rhino model is created in millimeters or meters to find a reasonable value.
- Specify a _grid_size with a panel
For BK3OV3 students, make sure your Rhino model is created in millimeters. Connect a value of 1000 to the _grid_size input.
Usually, sunlight calculations are calculated a little bit above the ground. Set a value of about 700 mm above the ground using a Number Slider.
- Set the offset distance from the ground with a panel
For BK3OV3 students, make sure your Rhino model is created in millimeters. Connect a value of 700 to the _offset_dist_ input.
Now we need to set the geometry where we want to calculate the sunlight hours on. This must be a surface an will internally be converted to a mesh.
- Add a surface parameter to the canvas
- Set your Rhino surface on the parameter
- Connect the surface parameter to the _geometry input
Calculating the sunlight without any context, wouldn't make any sense. Add another geometry parameter to the canvas that contains all the surrounding walls, buildings, ceilings, objects etc. that will block the sun. Connect this parameter to the _context input.
- Add a geometry parameter to the canvas
- Set your Geometry on the parameter
- Connect the geometry parameter to the _context input
Before you continue, please save your Grasshopper file. We will now calculate the final result, but if the calculation takes too long, you may lose your data. After saving, double-click on the Boolean Toggle of the _run input. A mesh with the sunlight data should now be visible. The colors of the mesh indicate the amount of sunlight on the ground.
- Save your Grasshopper file
- Double-click on the _run Boolean Toggle
Your sunlight analysis should now be visible in the viewport. If the colors are not clearly visible, temporarily hide your Rhino ground surface, and turn the preview off of the Grasshopper Surface parameter and Geometry parameter.
In the right image, you can see some yellow colors where there is sunlight. As you can see, the sun is still quite low at this time, because we set the hoy time to early in the morning.
If only one square is visible, or all you squares are blue, make sure that your Rhino model is set to millimeters.
Calculating the total amount of sunlight
The Result output can tell you the exact amount of sunlight for each square on your surface. If you connect a Mass Addition component to that output, the result will be the total amount of sunlight in your model.
- Connect a Mass Addition component to the result output
- Connect a panel to the Result output
Running the calculation with an Analysis Period
You now have an idea how long the calculation of one hour takes. Next, you can try to calculate a longer period by connecting the LB Analysis Period to the hoys_ input. Remember: the more hours you calculate, the longer the calculation will take. At the input of the Analysis Period, you can define a start/end month, day and hour. The interval will indicate the amount of intervals (minutes) that should be calculated per hour.
- Set the _Run Boolean Toggle to False
- Define an analysis period with Number Sliders
- Connect the analysis period hoys output to the hoys_ input
- Set the _Run Boolean Toggle to True
You now have a sun hours analysis over a longer period of time.
Tips and Tricks
Changing the settings of the sunpath legend is possible by connecting the LB Legend Parameters component to the legend_par_ input. Hold your mouse on the different inputs to read what the parameters can change. Using the script in the following image for example, you can change the coloring of the sunlight analysis to black and white.
If the legend is not visible, hide the surrounding geometry in Rhino.
If you have a modern laptop, it may be useful to set the parallel_ input of the LB Direct Sun Hours to True. This will enable multi-core processing in your script. The script may therefore run way more efficiently when calculating complex sunlight analyses.
Using Galapagos, it is possible to automatically optimize your model. For example: you may want to know the perfect location for you roof, to get the greatest amount of shadow in your design. By creating a Grasshopper model that has parameters to move your roof, you can optimize the location, based on the amount of sunlight. Take a look at the following tutorial to get an idea about how Galapagos works: Galapagos Optimization
If you are a student at TU Delft and you have a very complex Ladybug Analysis to calculate, you can use the BK renderfarm to execute the script for you. Take a look at the Renderfarm Tutorial, or contact @hok.
Final Grasshopper script
