Merge pull request #21 from open-pv/12-shadinggeometry-from-simgeometry

12 shadinggeometry from simgeometry

package.json

@@ -14,7 +14,7 @@
     "format": "lint-staged",
     "build": "tsup",
     "prepare": "husky",
-    "docs": "typedoc src/index.ts --plugin typedoc-plugin-mdn-links --plugin typedoc-plugin-coverage --plugin typedoc-plugin-rename-defaults --entryPointStrategy expand"
+    "docs": "typedoc src/index.ts src/utils.ts --plugin typedoc-plugin-mdn-links --plugin typedoc-plugin-coverage --plugin typedoc-plugin-rename-defaults --entryPointStrategy expand --excludePrivate true"
   },
   "repository": {
     "type": "git",

src/index.ts

@@ -5,19 +5,11 @@ import { viridis } from './colormaps';
 import * as elevation from './elevation';
 import * as sun from './sun';
 import * as triangleUtils from './triangleUtils.js';
-import { CartesianPoint, SphericalPoint, SunVector, isValidUrl } from './utils';
+import { CalculateParams, CartesianPoint, SphericalPoint, SunVector, isValidUrl } from './utils';
 
 // @ts-ignore
 import { rayTracingWebGL } from './rayTracingWebGL.js';
 
-interface CalculateParams {
-  numberSimulations?: number;
-  diffuseIrradianceURL?: string;
-  pvCellEfficiency?: number;
-  maxYieldPerSquareMeter?: number;
-  progressCallback?: (progress: number, total: number) => void;
-}
-
 /**
  * This class holds all information about the scene that is simulated.
  * A ShadingScene is typically equipped with the following attributes:
@@ -27,13 +19,13 @@ interface CalculateParams {
  *   responsible for shading
  */
 export default class ShadingScene {
-  simulationGeometries: Array<BufferGeometry>;
-  shadingGeometries: Array<BufferGeometry>;
-  elevationRaster: Array<CartesianPoint>;
-  elevationRasterMidpoint: CartesianPoint;
-  latitude: number;
-  longitude: number;
-  elevationAzimuthDivisions: number;
+  public simulationGeometries: Array<BufferGeometry>;
+  public shadingGeometries: Array<BufferGeometry>;
+  public elevationRaster: Array<CartesianPoint>;
+  private elevationRasterMidpoint: CartesianPoint;
+  public latitude: number;
+  public longitude: number;
+  private elevationAzimuthDivisions: number;
 
   /**
    *
@@ -56,12 +48,15 @@ export default class ShadingScene {
   /**
    * Adds a geometry as a target for the shading simulation.
    * For these geometries, the PV potential will be simulated.
+   * This geometry will also be used as a shading geometry, hence
+   * it is not needed to additionally add it by using `addShadingGeometry`.
    *
    * @param geometry Arbitrary Three.js geometry
    * @memberof Scene
    */
   addSimulationGeometry(geometry: BufferGeometry) {
     this.simulationGeometries.push(geometry);
+    this.shadingGeometries.push(geometry);
   }
 
   /**
@@ -121,13 +116,8 @@ export default class ShadingScene {
    * This function is called as a last step, after the scene is fully build.
    * It runs the shading simulation and returns a THREE.js colored mesh.
    * The colors are chosen from the viridis colormap.
-   * @param numberSimulations Number of random sun positions that are used to calculate the PV yield.
-   * @param diffuseIrradianceURL URL where the files for the diffuse Irradiance can be retreived.
-   * @param pvCellEfficiency Efficiency of the solar cell, usually this is a value close to 0.2.
-   * @param maxYieldPerSquareMeter Upper boundary of the mesh color in kWh/m2/year.
-   * In Germany this is something like 1400 kWh/m2/year multiplied with the given pvCellEfficiency.
-   * @param progressCallback function that handles the progress of the simulation, used for showing a
-   * loading bar on a website
+   * @param params: The input object containing information about the simulation.
+
    * @returns A three.js colored mesh of the simulationGeometry.
    */
 

src/utils.ts

@@ -1,3 +1,6 @@
+/**
+  @ignore
+ */
 export function isValidUrl(urlString: string): boolean {
   try {
     new URL(urlString);
@@ -6,6 +9,7 @@ export function isValidUrl(urlString: string): boolean {
     return false;
   }
 }
+
 export type SolarIrradianceData = {
   metadata: {
     description: string;
@@ -50,7 +54,41 @@ export type Point = {
   spherical: SphericalPoint;
 };
 
+/**
+ @ignore
+ */
 export type SunVector = {
   vector: Point;
   isShadedByElevation: boolean;
 };
+
+/**
+ * Interface for the parameter object for {@link index.ShadingScene.calculate}
+ */
+export interface CalculateParams {
+  /**
+   * Number of random sun positions that are used to calculate the PV yield.
+   * @defaultValue 80
+   */
+  numberSimulations?: number;
+
+  /**
+   * URL where the files for the diffuse Irradiance can be retreived.
+   * The object at this URL needs to be of type {@link SolarIrradianceData}.
+   * @defaultValue undefined - only direct irradiance is used.
+   */
+  diffuseIrradianceURL?: string;
+  /**
+   * Efficiency of the solar cell, value in [0,1].
+   * @defaultValue 0.2
+   */
+  pvCellEfficiency?: number;
+  /**
+   * Upper boundary of annual yield in kWh/m2/year. This value is used to normalize
+   * the color of the returned three.js mesh.
+   * In Germany this is something like 1400 kWh/m2/year multiplied with the given pvCellEfficiency.
+   * @defaultValue 1400*0.2
+   */
+  maxYieldPerSquareMeter?: number;
+  progressCallback?: (progress: number, total: number) => void;
+}