Terrain Shading Mask Component Release



EDIT: Both Terrain shading mask and Horizon angles components are now part of Gismo plugin. For future suggestions, issues, bugs, post a question in Gismo’ plugin group.


I would just like to make a modest notice about the two new Ladybug components, one of which creates a 3d terrain shading mask and another one which visualizes and exports horizon angles.

A terrain shading mask is essentially a diagram which maps the silhouette of the surrounding terrain (hills, valleys, mountains, tree tops…) around the chosen location, and account for the shading losses from the terrain.
It can be used as a context_ input in mountainous or higher latitude regions for any kind of sun related analysis: sunlight hours analysis, solar radiation analysis, view analysis, photovoltaics/solar water heating sunpath shading…

My home town is an example of the shading caused by the terrain. Here is how it looks from the tallest building in the town:

And the created terrain shading mask:

A mask for any land location up to 60 degrees North can be created:

There will also be a support for a few major cities above this limit.

Both Terrain shading mask and Horizon angles components can be downloaded from here.
An example .gh file can be found in here.

Component will prompt the user to download and copy certain files in order to be able to run.

It was created with assistance from Dr. Bojan Savric.
Support on various issues was further given by:
Dr. Graham Dawson, Dr. Alec Bennett, Dr. Ulrich Deuschle, Andrew T. Young, LiMinlu, Jonathan de Ferranti, Michal Migurski, Christopher Crosby, Even Rouault, Tamas Szekeres, Izabela Spasic, Mostapha Sadeghipour Roudsari, Dragan Milenkovic, Chen Weiqing, Menno Deij-van Rijswijk and gis.stackexchange.com community.

I hope somebody might find the components useful.


Very nice Djordje. Thanks!!

A question (or maybe suggestion). The sunpath and terrain resulting from the calculation are (for your example, for instance) too far away. Usually, for representation purposes you want to show the sunpath much closer to your site. So now i take the resulting projection and scale it together with the sunpath.

The question is: is there a way to control this more user friendly? I have to say that maybe i’m lazy with trying the min/maxVisibilityRadius_ inputs, but this because the computation takes a while :slight_smile:

Also, it is not clear for me from the explanations: when i already calculated the shading mask how can i save time for the next time. I see that some tif and obj files were downloaded to the ladybug/terrain directory. SO if you don’t mind, a further explanation will be appreciated.

Thanks again!!



Very awesome component, Djordje! This will be useful in a lot of cases.

I have one fatal error and one comment. I am unable to run your component on my machine because of a PINVOKE error (similar to what had halted our work on OpenStudio at one point):

Unfortunately, we never found to root cause of this error with OpenStudio as this long github issue suggests. The error just magically disappeared in the later OpenStudio releases. Mostapha, have you discovered anything related to this issue since the discussion?

My comment is that we really need to find some easier way to install this if we would like a large number of people to use it. Since the whole application is only 26 MB, I would suggest having an automatic download and extraction the first time that somone runs the component. You can sense whether the files are there the next time that the component is run. This is similar to what is done with genDayMtx.exe:


… or to the epw files from the URL:


I also second Abraham’s request for a scale input on the component.



Hi Abraham,

Thank you for the valuable suggestions!

You can remove any kind of geometry supplied to the context_ input. This will make the radius of the terrain shading mask equal to that of the Ladybug Sunpath component. This is what I essentially did in the upper photo of my hometown’s mask.
For now this is working only for metric units. I will make sure that for the next release at least feets are supported as well.

As for the saving of the time: try increasing the maxVisibilityRadius_ to say 300.
Depending on your PC configuration and internet speed it may take as long as 15 minutes for the component to run. The topography file will first be downloaded from opentopography.org. That’s the .tif file you noticed. Once the mask is created it will be saved to an .obj file. The next time you run it the mask will be imported from the .obj file, skipping the previous 15 minutes:

It still may take a a couple of minutes (depending on your PC configuration) for the component to complete loading of the mask. The reason why is: the mask needs to be scaled and centered according to the context_ input.

Also the next time a user decides to change the maskStyle_ input or context_ input, the topography data will not be downloaded from the opentopography.org website, but rather created from the .tif file.
For default maximalVisibility_ of 100, these .tif files are mostly a couple of megabytes, which is not that much of a burden on user’s hard drive space. On the other hand keeping these .tif files on user’s hard drive helps saving the opentopography bandwidth cap.
Let me know if I can answer any further detail or if this one hasn’t been clear.

Hi Chris,

Thank you too.

Please provide the following data:

  1. Zip the “terrain shading mask libraries 32-bit” folder in “c:\ladybug” in case you have x86 version of Rhino 5, or “terrain shading mask libraries 64-bit” folder in case you have the 64 bit version of Rhino 5. Upload the zipped folder, and post the link in here, please.
    Zip the whole folder, not its content only.

2) What is the full name of the GDAL libraries .zip file that you downloaded? What is your Windows version and Rhino 5 version?

On genDayMtx.exe and install of the GDAL libraries: I am reluctant to avoid manual install due to blocking issue. Copying two folders manually is quite a small price to pay in comparison with finding the blocked library among tens of them.



Sorry it took so long to reply. You can find the zipped folder attached.

The version of the GDAL libraries that I downloaded is release-1800-x64-gdal-1-11-4-mapserver-6-4-3.

I am sure that there is some way around the blocking issue although you may be right that an automatic download in the background might not be the best way to do it. I’ll talk to Mostapha about it at some point if it doen’t come up on this discussion.



Hi Chris,

Grasshopper forum supports only 5mb attachments. Upload the zipped folder to some file sharing website.

What is your Windows version and Rhino 5 x64 version?

I think it depends on windows version, (maybe even antivirus software, although I may be wrong on antivirus) whether the downloaded .zip file would be blocked or not.
One thing is certain: if a user unblocks a .zip file file and then extracts its content, none of the extracted files will never be blocked.
In my opinion the number of topics that we regularly receive on genDayMtx.exe would be much less if users would have to install the genDayMtx.exe manually (where installation would include a step with unblocking).


Thanks Djordje for the response.

Didn’t test yet.

But just want to remind that Marios Tsiliakos developed a component for unblocking the LB_HB components and libraries (Unblock All and Unblock).

Maybe these can bring some use here?

BTW i installed the release-1800-x64-gdal-2-1-0-mapserver-7-0-1.zip without issues (just unblocking).




Sorry for not realizing that it failed to upload. Here’s a dropbox link:


My version of Windows is 8.1 and I will try it out on Windows 7 and Windows 10 when I get the chance at work. All of these Windows versions will be 64-bit.

My Rhino is Rhino 5 SR12 64-bit.



Hi Chris,

Thank you for the upload. You do not have to check on other Windows versions. The upper error you posted was caused by not following the step 3 of the installation: You should have copied the content from the “bin” folder to the “c:\ladybug\terrain shading mask libraries 64-bit” folder:

So not the very bin folder, but its content.
Just do this and the component will work.

Hi Abraham,

But just want to remind that Marios Tsiliakos developed a component for unblocking the LB_HB components and libraries (Unblock All and Unblock).

Thank you for the suggestion. I am aware of that component. I shared an article about it on my facebook account last year, at the time when it was released. It’s a great component!
There are still two issues with it: It edits the windows registry.
I order for it to edit the windows registry it requires an account with administrator’s rights.
To unblock the file manually you do not need to have an account with administrator’s rights.

BTW i installed the release-1800-x64-gdal-2-1-0-mapserver-7-0-1.zip without issues (just unblocking).

Yes, the GDAL 2.x.x and MapServer 7.x.x versions will also work. But I can not install them on my PC, therefor I can not provide support for them. The GDAL 1.x.x and MapServer 6.x.x are sufficient for what the component does.
If you intend to seek support for any future issues, please install the latest GDAL 1.x.x and MapServer 6.x.x version as said by the component installation instructions.



I got it to run. Steps 3 and 4 were so similar that I missed one of them. If we can’t find another way because of admin privileges, I think most users will still tolerate a short manual install of downloading and unzipping.

However, why is it that the user needs to take all of the content out of the bin and CSharp folders and dump them in the main folder? If the user has installed the tool by downloading, unblocking, and unzipping the tool, can’t we just be sure that the required files are in the bin and CSharp folders as opposed to the main folder? So we search for them there as opposed to the main folder?

If we could get rid of steps 3 and 4, I think that it would go a long way to lowering the barrier to using the tool and would prevent dumb posts like the one that I have done here.



Hi Chris,

With all due respect, I am actually surprised that you have been confused by these two simple steps:

  1. Extract the downloaded .zip file content anywhere. Then copy the content from its “bin” folder to the “c:\ladybug\terrain shading mask libraries 64-bit” folder.

    4) Copy the content from its “bin\gdal\csharp” folder to the same “c:\ladybug\terrain shading mask libraries 64-bit” folder.
    That’s it!

Nevertheless, I have just introduced an article with installation photos to the newest version of the component.

To answer the second part of your question:

This would mean that the developer of the GDAL libraries would have to come up with a separate .zip file used by Terrain_Shading_Mask component only, for both x86 and x64 versions of Rhino5. He is not willing to do that.
Not hosting the libraries on developers website (gisinternals.com) but rather on ladybug github account or separate server may raise an issue with licensing, for which I do not wish to be accounted for.


Here are two question from the “daylight simulation using complex surfaces” topic by Giacomo Luddeni. I posted the answers to them in here as it will be beneficial to keep them in component’s release topic:

I’m wondering how does it decide where to place the mask (given that I put no input data as context_ in the TerrainShadingMask element).

As Abraham explained in your initial topic, if you do not supply anything to the context_ input it will create a mask with the same radius as the sunpath diagram from Sunpath component. This serves for visualization purposes.
So the photo you see in the starting post of this topic has been generated in that way.
However in order for the mask to be used as a shading context for any solar radiation analysis, it needs to be scaled. The component scales the mask until the difference between the sky exposure factors of four points of the context_'s bouding box is less than 0.01.
Then it should have done the same for the sunpath shading.
As I did not succeed in moving the whole “Sunpath shading” component to the “Ladybug Ladybug” component and calling it from there, this step is omitted. After checking for sky exposure factor differences, the radius will be scaled 3 times, and if lesser than 10000 meters, it will be set to 10000 meters. In most cases this kind of distant radius may not even be needed.

Is it actually placed in such a way to give the same shading effect as the real terrain geometry?



Hi Djordje,

I’m afraid that i get lost with your explanation. It is clear now that the mask should be scaled. What is not clear for me is the procedure in order to guarantee the right use of the mask as a context.

An example will be appreciated.



Hi Abraham,

The “Terrain shading mask” mask component will scale the mask inside of it, and output it (scaled) through its terrainShadingMask output. No manual scaling should be performed.
The scaled mask from the terrainShadingMask ouput can then be plugged to any other component’s context input.

What sort of specific example do you need?


Hi Djordje,


After your previous response i get a bit confused regarding the “correct” size of the mask in relation to the model geometry.

Now i want to think out loud and tell me if i’m right or wrong:

Running the terrainMask without context gives you the mask with the original sunPath scale.

This mask is calculated up to about 100km from the location.

There is no need to scale anymore the mask? But here, is one doubt. Say i have a large model or a small one. For the fomer i want the mask to be beyond the limits of the model, so i’ll scale it down …? This won’t affect the solar/radiation calculations results (or the other way around: scale up.

This is the kind of example/situation i want to be clear. I suppose and assume other will alsodo.




Hi Abraham,

Running the terrainMask without context gives you the mask with the original sunPath scale.

Yes, you are correct: if nothing is inputted into the context_ input, the radius of the final terrainShadingMask output will always be 200 meters (or 655 feets in case of Feet unit system). This corresponds to the default radius of the “Sunpath” component (sunPathScale = 1). This geometry is suppose to be used for visualization purposes only.

There is no need to scale anymore the mask?

Yes. No manual scaling should be performed. The “Terrain shading mask” component will perform the scaling based on the size of context_ input’s bounding box.

But here, is one doubt. Say i have a large model or a small one. For the fomer i want the mask to be beyond the limits of the model, so i’ll scale it down …? This won’t affect the solar/radiation calculations results (or the other way around: scale up.

The mask will always be scaled in a way so that it goes beyond the limits of the context_ input. It will never intersect with the context_ input. Unless your context input is consisted of a building blocks, a couple of hundreds of meters in diameter, somewhere high in the mountains: you will probably end up with 10 000 meters mask radius.

I didn’t understand you about the affect of the solar radiation results.
You mean: does scaling of the mask affects the solar radiation results?

Please let me know without hesitation if I missed to answer some of your questions.


Ok Djordje … just because you asked for that … :slight_smile:

The process of getting the mask is understood. The process of using it as a context for daylight/radiation/etc analysis is less.

So let’s assume two cases for the same location:

  1. Small scale. Only one room, where i want to get a daylight analysis.

  2. Big scale. Urban area (say 10 by 10 blocks, for the sake of the discussion), where i want to perform a radiation analysis on the blocks.

So, different scales, and different tasks. The question is, what would be the flowchart to do the job taking correctly the influence of the mask for both.

I believe i’m missing something from your explanation, but hopefully your answer will help not only me, but others to have a good and correct use of the component.

Makes sense what i’m asking?



  1. You would have to connect all the geometry you have (a room, and the ground surface around the room to the context_ input). The “Terrain shading mask” component would then scale the mask, and depending on the topography of your location you will probably end up with a 10 000 meters mask radius.

    2) Again you would plug in all the geometry (those blocks) into the context_ input. Depending on the topography of the location, you will probably end up with a mask radius higher than 10 000 meters.
    But in this case the default value of 0 of the minVisibilityRadius_ input needs to be increased, so that the topography near the location gets excluded. Which is exactly what the minVisibilityRadius_ serves for.
    To my knowledge there is no paper which describes the exact amount of the minVisibilityRadius_ which needs to be used.
    ShadeUp plugin for example uses 50 meters of minVisibilityRadius_ by default and 50 000 meters of maxVisibilityRadius_ by default, for objects of a tens of meters in diameter.
    Something similar can be applied to our minVisibilityRadius_ input. For example: for relatively flat location surroundings one can use minVisibilityRadius_ to be at least 3 times larger than the contextRadius output. For more hilly locations surroundings this value can be increased (6, 7 times of the contextRadius).
    For example if the contextRadius is 600 meters, minVisibilityRadius_ can be 3.6 kilometers, and so on.

    Let me know if this answers your questions.