Automatic Install

To install, open Sketchup's Extension Manager. Click 'Install Extension' and select the file SunHours_v2.0.8.rbz.

If there is an old version of the plugin already installed prior to this installation, restart Sketchup after this installation.

If this error message appears, then the problem may be that the plugins folder does not grant Sketchup the permission to copy new files there. This is particularly a recent problem on computers running OS X for all plugins, and can be fixed as follows:

  1. Navigate to the plugins folder: /Users/YOUR USERNAME/Library/Application Support/SketchUp 2017/SketchUp/Plugins
  2. Select plugins folder, then press Cmd+I (get info).
  3. In the window that opens, towards the bottom, find 'sharing & permissions' (you may have to click on the little triangle to fully open permissions).
  4. Click on the little padlock in bottom edge to get admin access, enter admin password.
  5. Set the permissions for the folder (for everyone) to read and write by using the dropdown menu.
  6. Now you should be able to use the Install Extension procedure correctly.

Manual Install

If this does not fix your problem, then extract the plugin files themselves from the provided ZIP archive, close Sketchup if it is running, and copy the files  (AlexHall_SunHours.rb and the accompanying folder) into the right location for your operating system, for example: 

Windows: C:\Users\YOUR USERNAME\AppData\Roaming\SketchUp\SketchUp 2017\SketchUp\Plugins
Mac OS X: /Users/YOUR USERNAME/Library/Application Support/SketchUp 2017/SketchUp/Plugins

See here for more information on installing plugins.


Fitting a Grid

To fit a grid to a face, select the face and click on: Extensions > SunHours > Fit grid

This will bring up a dialog with the following parameters for you to set:

  • A measure of density: how filled with the cells/rectangular faces should the grid be? There are three different measures you can choose from the drop down list:
    • Approximate width of cells (m): the plugin will make the lengths of both sides of the cells as close to the entered value as possible
    • Number of cells on long side: the plugin will adjust the size of the cells to ensure that the longer side of the grid can have cells up to the number that you enter.
    • Number of cells on short side: similar to the above, but choosing the same value will result in greater density.
  • Height to raise grid off face (m): The grid will be translated after fitting directly away from the top/front of the face by the distance entered.
  • Exclude interior nodes: If checked, nodes that aren't sufficiently close to any of the sides of the grid will be removed.
  • Number of nodes: If the above is checked, this will determine the furthest that a node can be without being excluded. For example, entering 2 will remove all but the nodes on the very edge and those directly adjacent. A higher number will exclude fewer nodes.
  • Distance to offset face inwards (m): The grid is in fact fitted not to the face selected, but to a copy of the face created as though the "Offset" tool were applied to the original, using the distance entered. Therefore the grid will start the entered distance away from the edges of the face.

Click "OK" to confirm the parameters and fit the grid, which will then be selected automatically.

Important Notes

  • You can select multiple faces and even curved surfaces, and a grid will be fitted to every face/surface selected. The selection can contain other entities such as edges; they will just be ignored. The faces and surfaces can also be oriented in any direction and need not be any shape in particular.
  • If you select several flat faces that all lie in a single plane, even if they are far from each other, a single grid will be fitted to the whole group. If this isn't what you want, then fit grids to one face at a time. Moreover, if some of these faces are connected by common edges, then these edges will be virtually deleted (not affecting the originals) so that a single offset is applied to the set of connected faces as one face, to avoid unwanted gaps in the grid.
  • Groups and components will be ignored: you must explode them before fitting a grid or doing any analysis.
  • The grid will be parallel to the face, and the distance from the face to the grid will be the height entered. A positive height will move the grid to be above the face, and a negative height below. If the face is oriented vertically, then the grid will be moved away from the 'front' of the face as determined by Sketchup. This can sometimes mean that the grid will be moved out of sight, so if you can't see the grid after fitting, consider this. Refit the grid with a negative height to fix the problem.
  • Like with the actual 'Offset' tool, strange results can occur if a large offset distance is entered. Avoid entering a distance that is large in proportion to the dimensions of the face.
  • Nodes (points at intersections of gridlines) are what will be analysed. Nodes that aren't on the face or can't be projected onto a surface are considered invalid and are left out. A cell face is added if and only if all of its corners are valid nodes in the grid, so a cell can appear above a 'hole' in the face. More importantly, this means that not all valid nodes are always visible. Don't worry if few cell faces appear in the fitted grid: when analysing, results will also show for nodes that aren't a corner of any valid cell.
  • The positions of nodes when the grid is originally fitted are stored and used in calculation. The analysis will not use the actual positions of the vertices in the grid. Therefore you mustn't move, scale or rotate a grid before analysis.

Techical Details

  • Cells will be made as close to square as possible. This is how the plugin decides how many cells should be on the short or long side of the grid when you set the opposite number. However, the dimensions of the grid itself are determined before the density and they must be evenly divisible by the side lengths of the cells. This means that the cells will usually not be square, and in particular if you choose the density option "Approximate width of cells (m)", both side lengths will usually not match the value entered.
  • The gridlines are aligned with the x and y axes when fitting, and not necessarily aligned with the face, so don't be surprised if the grid seems rotated relative to the face.
  • If you enter a value of 0 for the offset, the plugin will correct this to a very small positive amount. Otherwise, when you fit a floor within a building, points on the edge of the grid would be considered 'outside' and hence often in the sun when they shouldn't be, since their position is on the wall which can be thought of as in sunlight.
  • Surfaces are fitted by determining an average orientation and then having a normal flat grid projected on them. This method will sometimes work poorly, especially if the surface is complex and has 'folds' in it. In that case, split the surface up manually and fit several grids.

Analysing the Grid

To analyse a grid, select it and click on:
Extensions > SunHours > Calculate sunlight hours
You can select as many grids as you want to analyse them all at once. The analysis will calculate for how long each node is in the sun over the given time.

The dialog that appears is mainly concerned with the dates and times for which the analysis is run. There is a great deal of control here, which works at three levels:

1. Time periods within a day:

You can choose which times of day the grid is analysed by setting start and end times for one or more periods. The 'Add another period within a day' and 'Remove the last period within a day' buttons will let you choose how many periods you want. Note that the time periods must not overlap and each must come after the period before it: in other words, all times entered must be in order. Here is an example of setting two time periods within one weekday type (discussed next):

If the time step entered further down is 0.5 hours, then the grid(s) will be analysed at the times:

8:00, 8:30, 9:00, ... , 12:30, 13:00, 14:30, 15:00, ... , 17:30, 18:00

2. Weekday Types:

As the analysis moves from day to day, it can select a particular set of time periods based on what day of the week it is. The screenshot on the left shows the default settings, which has two weekday types. The first is applied from Monday to Friday, and the analysis on those days runs from 7:00 to 18:00. The second type runs for a shorter time on Saturdays only. The analysis will skip Sundays because there is no type associated with them.

Every type has associated with it a set of weekdays that it applies to and a set of time periods. In the example on the left, each type has only one time period, but you can have an arbitrary number for each type. You cannot associate multiple types with any day of the week.

Just as you can add and remove time periods within a day/type, you can add or remove types.

3. Date Periods:

Finally, you can choose on which days the analysis is run by specifying multiple periods of days with start and end dates, similarly to setting time periods within each day. All the weekday types and their associated time periods will be used for each period of days. Clicking on a date field will bring up a date picker to choose a specific date. You can also choose an equinox or solstice from the drop down list on the right. This example shows two date periods, but as always you can choose to have just one or any greater number of periods.

After all the time related settings, there are a few additional options:

The time step is the spacing between times that the grid is analysed in. A shorter time step will result in a more accurate analysis but will take longer. Fractions of an hour can be entered. The minimum is 1 minute.

You can choose to save the exact results of the analysis in a CSV file by entering a location, preferably using the ‘Browse’ button. All the results, for all the grids that were considered in this analysis, will be contained in a single file. The file will first show you how long the analysis was in hours (i.e. the maximum time that any point could be in the sun) and how many days were analysed (after possibly excluding certain days of the week) for you to calculate average or percentages. Then, for each grid in the model, there are up to three grids of results. The first, labelled ‘Totals’, is the total number of hours that each node was in the sun during the entire analysis period. If you opt to include them, there will also be grids labelled ‘Maximums’ and ‘Minimums’, which are explained below. The results for each grid in the model are labelled in the file by a grid ID. Right clicking on a grid in the model will show its ID at the bottom of the context menu so that you can match up the file results with the model.

Ticking the option to include daily maximum values in the CSV file will add an extra grid of data to the results. This data gives the greatest number of hours in a day that each node was in the sun, i.e. a sort of 'worst-case scenario'. So if a node says 8 hours, that means that on some day, the node was in the sun for 8 hours, and every other day the node was in the sun for that long or less. Therefore different nodes probably correspond to different dates (these are not given). Including minimum values is similar but the opposite.

Once you've chosen all your settings, click OK to begin.

The calculation can take some time, so be wary of analysing dense grids, low time steps, or long periods. An indication of progress will be shown in the status bar:

When finished, the grid looks something like this:

Important Notes

  • Remember to set the time zone (in Sketchup's shadow settings dialog) and the location of the model before performing analysis.
  • Regardless of the file name you choose, '.csv' will be appended, allowing you to open the results file in a spreadsheet viewer.
  • The file is saved as read-only because any change made to it, even just saving it from a spreadsheet program, will likely make it unreadable when trying to import analysis later. You are advised to make a copy for any calculation, presentation, or other uses.
  • If the start time for a period begins before sunrise on a particular day, then analysis for that day will instead start at sunrise. Similarly, analysis ends at either the specified end time or sunset - whichever comes first. So if your only time period is from 10:00 to 15:00 and analysis is run for 10 days, then the total time analysed in hours given in the file may be less than 50 hours.
  • Hidden entities are ignored during calculation. Grids are hidden during analysis so that they don't interfere. Transparent entities are treated in the same way as any other, so windows should be hidden or deleted. If any hidden entities are found in your model, you will be warned in the settings dialog for dates and times.

Technical Details

  • If the sun hits a node at a particular time analysed, then the amount of time added to the results is the time step, unless the end time for analysis (either specified or sunset) is sooner than the time analysed plus the particular time step. For example, if you specify the time period 13:30 to 14:00 with a time step of 20 minutes, then 20 minutes will be added to the results grid if the node is in the sun at 13:30, while only 10 minutes will be added if the node is in the sun at 13:50.
  • The model itself stores the grid IDs used already. If you perform analysis, delete the grids, save the model, and then perform some more analysis, the new grids will have new, unique IDs. However, if you do some analysis but then close the model without saving, then the next time you perform analysis the same IDs will be used again and you might have overlapping IDs in your result files.
  • Because of excluded weekdays, it's possible for the total analysis time to be zero hours, which creates nonsense output.
  • The simulator assumes that the year is 2015.

Color Settings

After analysis, the cells of a grid are colored according to the results of the analysis and a color gradient that you can specify. When grids that have the same color settings are selected (and no non-grids are included in the selection), a small color scale will appear in the corner of the screen to give you an indication of how much time in the sun is represented by various colors. If the scale does not appear at any point, try clicking on a grid again to select it. The value at the top of the scale is the total number of hours in the analysis. Clicking 'Edit scale' will bring up a dialog that lets you specify color settings:

The maximum and minimum catchall colors are single colors that a cell will take on if the corresponding checkbox is ticked and the amount of time that the cell is in sunlight is greater than the maximum value or less than the minimum value, respectively.

The colors in between form a gradient, where the higher a color is, the more time in sunlight a cell must be to have that color. You can add or remove colors using the '+' and '–' buttons, and can have from 2 up to 7 colors. If you uncheck the box for a maximum catchall color, then the top color in the gradient (red in the above example) will be used as the catchall color instead. A similar rule applies to the minimum color.

By default, the color of a face in the grid is based on the average of the total hours of the nodes at its corners. The last option in this settings dialog lets you choose instead to color cells based on the corner node that has the lowest or highest value by selecting from the dropdown list.

Once you are happy with your settings, you can click 'Apply' to recolor the grid and refresh the scale, but keeping the settings window open if you would like to make further changes. Clicking 'OK' will apply the settings and close the window.

If multiple grids with different color settings are selected, no valid scale can be shown and a grey box will appear instead. However, you can still edit the scale and apply the color settings to all the grids selected. Note that if grids are selected where the color settings are the same but the total hours analysed are different, a scale will still be shown, with only one total.

Miscellaneous Functions

Using IEQ settings

This plugin was designed with the Green Star SA IEQ-5 Daylight Glare Control credit in mind. The default settings of the plugin for fitting grids and for dates and times are chosen based on this. In these settings panels, if the settings are changed, you can click 'Restore IEQ defaults' to change the settings back to the defaults.

You can also select one or more faces and click 'IEQ wizard' under the Extensions > SunHours menu to conveniently fit a grid and then immediately analyse it using the IEQ settings.

Making default settings

In all the settings dialogs, you can click 'Set to default' to save the settings within the model so that when the dialog is reopened the same settings will appear. Newly analysed grids will also be colored using default settings that you choose.

Note that these default settings are attached to a model and not to the plugin. When you open a new model, its default settings will be the IEQ settings that the plugin starts with. Additionally, if you set default settings but then do not save the model, the defaults will be lost.

Attaching results to nodes

If you right click on a grid that has been analysed, you can choose 'Attach results to nodes' to see the numerical results directly on the grid in the model. You can then right click the grid again and choose 'Remove results from nodes' once you no longer wish to see them.

Refitting grids

After fitting a grid, you can right click on it and choose 'Refit grid' to fit the grid again to the same faces but with different settings that you can select. This is to allow you to consider various parameters for grid fitting.

If the grid has been analysed, this will be lost from the model, as really a new grid is being created. Saved .csv files will not be affected. If any faces originally used to fit the grid have been deleted, modified or used to fit other grids, this will not work properly.

Importing analysis

If you right click on a grid and choose 'Import analysis', you can select a .csv file created in a previous analysis and apply the results in the file to the grid without recalculation or reanalysing. The dimensions and shape of the grid in the model and the results grid in the file must match. If there is more than one possible results grid in the file with matching dimensions and shape, you will be asked to select the correct results grid based on the grid IDs given in the file.


A Problem for Windows Users

Several Windows users have reported that the plugin causes Sketchup to crash completely when they perform any kind of analysis. Currently the recommended fix for this problem is the following sequence of steps:

Windows > Preferences > OpenGL Settings > Disable hardware acceleration (tick the box).

Note to Users of version 1

The ability to see and edit a color scale, refit grids, or attach results to nodes, depends on data that is only stored when creating a grid in the new version. Grids created in the old version do not have this data and hence do not support these functionalities. When working with old grids, you may encounter messages warning you of this when you try to use newer functionality.

If you fit a new grid directly from faces as normal, then it will be possible to refit it.

If you analyse a grid or import analysis onto it, even an old one, it will then be possible to view a color scale or attach numerical results to the nodes. It will still not be possible to refit the grid. However, having gained some of the new functionality, the grid will no longer be considered 'old' by the plugin. Therefore, if you click 'Yes' in response to the offer in one of the warning messages to delete all grids created with the old version, this particular grid (or any other grid that was created in an old version but was analysed with this version) will not be deleted, even though it still cannot be refit.