Grasshopper API manual
AiPlantCare Grasshopper plugin is open-source API to AiPlantCare cloud computing services.
Install Grasshopper plugin
AiPlantCare Grasshopper plugin is an open-source and free-of-charge API to our cloud computing services. This feature helps designers and architects who have already a 3D model in Grasshopper or Rhino and wants to evaluate lighting situation for occupants and plants.
AiPlantCare plugin makes it possible to upload your project specifications and 3D geometry to our server smoothly. Cloud-based computing services makes it easy to benefits from powerful simulation engines such as Radiance.
There is no need for installation of these tools, preparing geometry and material, and dealing with steep learning curve to get it ready for annual daylighting assessment or calculating photosynthetically active radiation (PAR) and daily light integral (DLI) for plants. By downloading the result files (*.csv) post processing and visualizing the performance indicators will be easy in Grasshopper.
Installation: You can install the AiPlantCare package manually by downloading it from Food4Rhino.
Place the downloaded files (*.ghuser) in the User Objects folder C:\Users\...\AppData\Roaming\Grasshopper\UserObjects. That folder can be found in Edit > Special Folders > User Objects Folder.
Video Tutorial AiPlantCare - Rhino Grasshopper API
This video includes:
How to download and install the grasshopper components from Fod4Rhino
How to register on the website and get your API-Token. (Early access is free of charge!)
How to use our Ready2Use template and start your first simulation
How to load the results and start post processing and visualization
Make your account at aiplantcare.com
Go to the sign up page and register to get started. Early access is free of charge.
You may decide first to use a free service or benefits from unlimited professional features by reading the advantages in here.
By starting an account, you can use web-based tools and cloud services, as well as the Rhino API services. Logging in to your account leads you to your Dashboard. Dashboard includes your projects, plant species data sets, and simulation set-ups. You can always access to the archive of your models and results. Warning! for the early access all these features are enable until the expiration date.
Dashboard includes your Projects | Plants | General Settings | Payments. After activating your Early Access in "Payments", you should go to “General Settings”, to get your API token for using in Grasshopper Plugin.
Create a new project and start cloud-based simulation
The AiPlantCare Call is the main Grasshopper component to communicate with our cloud base services. Having an AiPlantCare account, you can get your unique API token from your Dashboard. Your “Username” should be as your registered account in our website.
The “Project Name” can be set as you wish, and you can access to the results under the same project name. Keep in mind that if you have already simulated a project with this name, running with the same name retrieve the already existing data on the cloud.
You need to specify the location of your project. You can just specify your latitude and longitude, and then the system will find the closest weather station to your project automatically. Alternatively, you can give us a link to the TMY weather data you want to use in your study. This link should be a downloadable link to a file with epw format. You can find many of these file on the energyplus.net/weather-download webpage free of charge.
The geometries and material setting should be defined and converted to obj format under the same project name before any call to our cloud server. This obj file must be generated by using following components based on our protocols for layer names and materials.
AiPlantcare_Rh2Obj > convert Rhino geometry into obj file format
AiPlantcare_Material > assign material to each layer name. This can be solar transmittance for windows or reflectance of opaque surfaces. We also suggest to define trees under win group and adjust its properties by using transmittance (0: a tree with dense foliage; >0.8 : an almost naked tree). And workplanes should be named as wp0, wp1, ...
When everything seems ready press the button once to Call to the AiPlantCare server. This process may take few seconds regarding to the size of your model, the number of sensor points. You can later check on your online dashboard if the project is online and whether the simulation is started or not?
The simulation may take few minutes based on the size of your model, the number of sensor points, and rayTracingQuality choice. The rayTracingQuality specifies the Radiance simulation parameters. Under the hood, we run a DC method simulation and you can adjust it to get a higher quality in your results (by default rayTracingQuality == 1: ' -ab 3 -ad 1024 -ar 1024 -as 128 -aa 0.1').
Prepare the model for simulation
Building 3D geometry
In Rhino environment, the 3D geometry for analyzing may include unlimited number of surfaces and meshes (delete all points, lines, curves). This model however should be simple as recommended for a daylight simulation. You should categorize the surfaces into main categories of opaque or transparent surfaces.
The opaque surfaces and obstacles with the same reflectivity value (or color) should be set in one layer (with specific layer name that you can recall later). Reflectivity can vary in the range of 0 (dark) to 1 (bright).
The window surfaces with the same transmissivity should be set in one layer (with specific layer name that you can recall later). Transmissivity can vary in the range of 1 (fully clear) to 0 (fully tinted/dark). For instance, if you have walls and ceiling with the same color or reflectivity, they should be defined as one opaque layer (e.g. opaque0 with Ref. 0.6). If you have two different window one darker than the other more transparent, one can be set in layer Win0 (Trn. 0.60) and the other in Win1 (Trn. 0.85). The layers must be named carefully, since the material properties will be assigned later corresponding these names.
Keep in mind that the window opening needs to be cut through the wall or the ceiling. Normal vector of the faces are not important but for the work planes analysis mesh.
If the 3D model is generated in Grasshopper environment, it must be baked first with the required layers names. You can use the AiPlantCare baking component, which gets a geometry and a layer name and bakes your generative model, as it is required.
Work plane
The work plane (aka. analysis mesh) is an imaginary plane that you want to evaluate the level of daylighting on that surface. So, it can be a horizontal plane above the floor (normally 80 cm) or a vertical surface close to the wall you want to place a green-wall. The work plane can be either inside the room or outside on the façade surface. To create the work plane a mesh with desire discretization should be created in Rhino or Grasshopper.
The number of meshes as well as the normal vectors orientation are very crucial because the system will set the sensor points resolution and their orientation (e.g. facing upward or downward) based on this analysis mesh. These virtual sensor points represents a lux meter or par meter sensor on that exact place and after the calculation you can get hourly values on each sensor point. The higher the number of sensors the higher resolution in your results and the more required computation power and simulation time.
It is highly recommended to check normal face of these meshes in Rhino under “Analyze > Show Object Direction”, before starting any simulations. Multiple number of work planes can be defined. Finally, the analysis meshes should be baked and set with the correct layer names as “wpx”.
Keep in mind that at least one work plane needs to be exist in your model. Projects without work plane (sensor points) cannot be simulated. Any other unnecessary layers, objects, surfaces, lines, curves, and points must be removed from your Rhino model. The orientation and elevation of your model must be set carefully (+y in Rhino is assumed toward North) before using the Rh2obj component.
The projectName.obj is a copy of the geometry used for the simulation. It will be generated in your local folder: C:\Users\...\Local\Temp\aiplantcare\ if only the writeObj input in AiPlantcare_Rh2Obj component was set to “True”.
Material setting
AiPlantCare benefits from Radiance simulation engine and every material in your model is translated into simplified material types readable for Radiance. For defining the surface properties, you can use “Material Setting” component in Grasshopper.
Warning! Each visible layer name in Rhino will be converted to .obj and will be used in our simulation. Therefore, each layer must have a corresponding material definition here in py code under one of these groups (dictionaries):
You just need to open the py code and make sure your layer has a line and is set to an input to the component such as trans1 or reflect1.
The opaque surfaces are defined as “plastic” material where the reflectivity value is used for all three RGB channels equally (no color, only gray) with no roughness and specularity. Other obstacles, objects, furniture were treated as opaque surface as well.
The window surfaces are defined as “glass” material where the transmissivity value is converted into transmittance and used for all three RGB channels equally (no color, only gray). The tree canopies can be defined as glass material. Therefore, if you want to represent a tree with a dense foliage, you can use low transmissivity value and if it allows more light to be passed through, you can define it with higher transmissivity value.
Workplanes are imaginary surfaces and are not considered as real obstacle in you model. Please keep in mind that the work plane should not cover any other surfaces. In this case, that part of the surface will be disappeared as well.
Loading the results in Grasshopper
After a successful simulation on the cloud, the resultant files as below will be downloaded on your local folder: C:\Users\...\Local\Temp\aiplantcare\
ProjectName.pts includes the position of sensor points (x,y,z) and the normal vectors (x,y,z)
ProjectName.ill includes the hourly photometric values (illuminance - lx) for each sensor point. It normally goes from 0 to 8760.
ProjectName.par includes the hourly photosynthetically active radiation (PAR, weighted in 400-700 nm range) values (μmol/m².s) for each sensor point. It normally goes from 1 to 8760 hours over a year.
ProjectName.dli includes the daily light integral (DLI) values (mol/m².day) for each sensor point. DLI expresses the total amount of PAR, which is accumulative on a surface in 24 hours. DLI for each single day over a year can be shown (from 1 to 365 days).
For post-processing and visualizing you can open these csv files in excel or you can use the component below to load the results in Grasshopper.
Annual Metric for Biophilic design
We calculate hourly PAR values on the sensors-grid and Daily light integral (DLI) which have been used in horticulture for decades to express lighting for plants, We introduced annual metric to evaluate the buildings in an early stage of design:
Annual DLI Autonomy (DLIa10) is an annual metric which describes how many day in year (as percentage), a certain point in a room receives enough natural daylight (DLImin based on the type of cultivar, e.g. 10 mol/m²∙d ).
Spatial DLI Autonomy (sDLIa10) describes how much space receives enough DLI (in DLI-target range) over the course of a year
Annual PAR exceeded (APE350) was defined to be checked as a pass/fail metric. APE describes how many hours on a certain point a room receives too much sunlight (above PAR cut-off e.g. 350 μmol/m²∙s). The value for PAR cut-off is based on the light saturation point of plant species and may range from 90 μmol/m²∙s to 350 μmol/m²∙s respectively for tulip and rose.
Spatial Annual PAR exceeded (sAPE350) describes how much of space receives excess PAR (assuming the cut-off upper limit, e.g. 350 μmol/m²∙s).
Annual Risk of Plants SunBurn (RPS350_5hr) describes how many days in year on a certain point in a room receives PAR above cut-off level (e.g. 350 μmol/m²∙s) and longer than the daily limit (e.g. 5 hours in a day). This metric shows the risk of plant sunburn when plants do not have enough time to overcome light stress.
Total Annual electricity demand for artificial lighting (kWh/year) and lighting schedule, an hourly time series profile with required fraction of supplemental light (0-1). These calculations are based on the selected Grow Light’s parameters such as: location in the room and Photosynthetic Photon Flux Density (PPFD). PPFD is the amount of light that actually reaches your plants within the PAR spectrum in μmol/s.m².
Annual shading schedule, an hourly time series profile with required fraction of sun protection on your windows (0-1) for a complete year. This profile is calculated based on receiving excess PAR (assuming the cut-off upper limit, e.g. 350 μmol/m²∙s) in different places in the room.
Analysis and visualization
Climate based daylight analysis for both humans and plants:
Point in time daylighting for occupants: hourly illuminance values (lx) and its distribution on the work plane over the course of a year (8760 hrs).
Annual daylighting for occupants: Useful Daylight Index (UDI%) is a daylight availability metric that corresponds to the percentage of the occupied time when a target range of illuminances (e.g. 300-2500lx) at a point in a space is met by daylight. This metric describes the amount of time a space is either: Too Dim (UDIs: supplementary), Well lit (UDIa: acceptable), or Too bright (UDIe: excessive). The occupancy schedule (how often and from when to when the space will be used) is also an important input for this calculation.
Point in time DLI for plants: daily light integral (DLI) values (mol/m².d) and its distribution on the work plane over the course of a year (365 days). DLI) describes the number of photosynthetically active photons (PAR in 400-700 nm range) that are delivered to the work plane over a 24-hour period. This metric describes very well the available light for plants. Each plant species (cultivar) has a DLI target which growth of that plant can be guaranteed. By comparing DLI available to DLI target the supplementary light requirement can be estimated.
Annual DLI for plants: DLI% index is a sunlight availability metric for plants that corresponds to the percentage of days when DLI target at a point in a space is met by natural light only. This metric also describes the amount of time a space is either: Too Dim (DLIs: supplementary), Well lit (DLIa: acceptable), or Too bright (DLIe: excessive). For this study, desired plant species and the corresponding DLI target should be selected first.
Electricity consumption for supplementary lighting (kWh)
In a human centric design, we consider the location of the occupants in the space and estimate the total electricity energy needed for supplementary lighting (artificial lighting) in addition to the natural daylight. If the place is closer to the window or skylight, this energy consumption is less. The occupancy schedule is also an important input for this calculation.
By selecting one the sensor points (among all points on the work plane), we assumed that the lighting control should be controlled based on the available natural light on that specific point.
In this component, a target range is defined. If the natural light on the sensor goes below the lower limit, the light turns on (100%) and if the available light goes beyond the upper limit the light turns off (0%). A linear dimming function is assumed for the values between the lower and upper limits.
The electrical power (watt) and the efficacy of the luminaries for humans (lm/W) and equivalent Photosynthetic Photon Flux Density (PPFD) factor of the lights needs to be specified by the users. PPFD factor shows the equivalent amount of photometric values (illuminance - lux) which can be used actively for photosynthesize in plants.
In a plant centric design, we consider the location of plant(s) in the space. It may be the whole area or a limited area that you consider for indoor growing. The estimation of the total electricity energy then will be done based on the selected sensor point. If the surface you are going to cover with a green wall for example does not receive the same amount of light, the position of your sensor matters more. Then if you locate the sensor in a place darker than the average, the energy consumption is overestimated and vice versa.
For plants, the occupancy schedule is not required since the plants supposed to be there all day long.
The lighting control is based on the available natural light on that specific point. For plants, DLI target range is used as lower and upper limits.
The electrical power (watt) and the equivalent Photosynthetic Photon Flux Density (PPFD) of the grow lights needs to be specified by the users. The PPFD values can be found easily on the grow lights providers’ website or products specifications.
Plants species datasets
For assessing the daylight situation for your plant, it is required to define an optimal range of DLI for plants. This data is available for most commonly used houseplants: Houseplants, Cacti and succulents, Greenwalls, Edible, and Purifiers plants.
Our database on the website includes larger number of plants species (+100,000) and a feature to recognize your plant from an image.
Last updated
