Scene

What it is

The system in three dimensions: every fixed rack and single-axis tracker at its own position and orientation, and the buildings, walls, trees and tanks that shade them. All lengths share one unit of the user's choice, which never enters the result.

Typical values and how to get it

Empty (null) runs the flat array section. Write the scene JSON from the layout drawing, a KML file or a PVsyst variant file.

Start from the example closest to the site. GET /api/scene-examples lists the examples with the racking changes each one assumes (array_patch, to merge into array) and its notes; GET /api/scene-examples/{id} returns the scene body. residential is a pitched house roof with its modules and trees, commercial rows of racks on a flat roof among rooftop units, ground_fixed fixed racks on sloping ground, ground_tracker single-axis trackers on sloping ground and east_west east-west ridges on flat ground beside a building and a tree. Keep the frame block, replace the types and placements with the layout converted to one unit (metres or feet, the same for every length), validate with POST /api/scene/validate, then run. Convert geographic coordinates with any local tangent-plane projection centred on the site, or on a central point of the layout when the file gives no site point: the centroid of the device centres and the centroid of the boundary both serve. Over a few kilometres the distortion is below the model's sensitivity.

Roofs and trackers. A rooftop array is a gft type placed on the roof plane (tilt = the roof pitch, z = the height of the array centre). Row-to-row shading must be off: set array.inter_row_shading to false, as the residential example does, or set array.track_mode to rooftop, which turns it off as well. Leave bifacial out; a building is one or more prisms. The two settings give the same result with the default thermal model; rooftop also refuses tracker types and a bifacial section, raises the NOCT to 49 °C under the NOCT thermal model, and still describes the roof when the scene is removed. Neither changes the heat-loss factor: set thermal.u_c to about 20 W/(m²·K) for modules close to the roof. With row-to-row shading off the array section's ground cover ratio, collector width, inactive bands, string strips and row count are not read, so they can keep any value. The AC section of GET /api/defaults belongs to a utility plant: its auxiliaries and its medium-voltage transformer and line take most or all of a rooftop system's production. For a rooftop system set ac_losses.use_auxiliaries, ac_losses.use_mv_transformer and ac_losses.use_mv_line to false (or their values to 0) and keep the AC wiring loss; a run whose energy to the grid is zero or negative says so in summary.warnings. The objects still shade with row-to-row shading off. Rows of tilted racks on a flat roof keep row-to-row shading on, like rows on the ground. Tracker rotation limits, backtracking and stow are set in the array section, not per tracker. The keys are rotation_limit_deg (or rotation_min_deg and rotation_max_deg), backtracking, and wind_stow with wind_stow_speed_ms and wind_stow_angle_deg, and they apply to every tracker of the scene.

The array section beside a scene. The scene gives every device its kind, tilt, azimuth and roll, so the array section's tilt and azimuth are not read, except that east-west racking reads azimuth_deg as the ridges' bearing to tell the east-facing faces from the west-facing ones. Of its racking types rooftop and ewf have an effect. With rooftop the fixed racks run as rooftop racking, without row-to-row shading. With ewf the scene holds east-west ridges: the east-facing faces and the west-facing faces are blended separately by module count, and the east-west energy model combines them module by module as on flat east-west racking. Rooftop racking takes gft types only; a scene that places sat types is refused until array.track_mode is fixed or single_axis. The array section supplies the rest: the tracker operation, the row-to-row shading switch, the ground cover ratio and collector width that the row-to-row model, the backtracking and the pitch check read, the inactive bands, the row count of the ground-reflection view factor (one over the row count) and the stringing, which sets the system nameplate. Set array.track_mode, tilt_deg and azimuth_deg to match the scene anyway, so that a run without the scene still describes the system. The type width in the scene and the array section's collector width in metres describe the same collector; with row-to-row shading on, keep them consistent after converting. The PVsyst import sets array.n_rows to the number of placed devices, which is right for rows of racks and for trackers and pessimistic for many short tables; edit it to the row count then.

The run. Placements of one kind whose planes have the same tilt and azimuth, rounded to the nearest 1° of tilt and 2.5° of azimuth, share one irradiance calculation (an orientation bin). A rack's roll enters through the tilt and azimuth of its rolled plane; a tracker at azimuth 0 and one at 180 are two bins even at tilt 0. The run counts the bins in summary.scene.n_bins, and POST /api/scene/validate reports the same count as orientation_bins. The bins are blended by module count before the module and inverter models run once. With the shading-factor table or the direct projection chosen on the Model tab, the neighbouring devices and the objects are projected onto each device; with the other row models, the array section's rows shade every device, corrected by the height difference to the device ahead, and the objects shade as seen from each device's centre (see the objects page).

Checks. POST /api/scene/validate checks the schema and the ids and returns the counts and the parser's warnings (an unused type, a roll on a tracker, a non-convex prism). A key of an earlier scene format is refused with a message that names its replacement. The origin distance to the site (limit 10 km), the pitch check and the module-total comparison need the site: POST /api/run reports them in summary.warnings, or as a 422 for the origin. The pitch check divides the spacing of each device to the one ahead of it by the type width and compares it with 1 over the array section's GCR, so the scene unit cancels; it warns above 1 %. On east-west racking it compares the ridge spacing (each face to the face of the same facing on the next ridge) with 2 × width × cos(tilt) / GCR, the GCR being the two faces' horizontal footprint over the ridge spacing. It concerns the row-to-row model and does not run with row-to-row shading off, as on a roof. summary.warnings carries these checks and the run's other warnings, such as an energy to the grid of zero or less. The run's summary.scene gives the bin and table counts and summary.scene_bins one entry per orientation bin (kind, tilt, azimuth, module total, table ids).

Site and weather. The scene does not move the site: set site to the system's coordinates, elevation and time zone, and load a weather file for that place (moving the site does not move an embedded weather series). The sun position is computed for site alone. If you projected the layout yourself, the projection centre is the origin: put it in origin, or make it the site, or both; they must agree within 10 km. The array_patch of POST /api/parse-scene is a shallow merge: copy each key over the same key in array. It carries no stringing. The stringing and the inverter section set the nameplate and the inverter loading: set modules_per_string, strings_per_inverter and n_inverters so that their product equals the scene's module total and choose an inverter of that array's size (GET /api/library/inverters), or accept the module-total warning, and the run gives the racking section's system at the scene's orientations and shading. The library's smallest inverters are about 7 kW AC; for a smaller array upload the inverter's OND file (POST /api/parse-ond) or give the inverter section inline from its datasheet, and check the string voltage against its window (Modules per string page). With east-west racking (array.track_mode ewf) the scene holds ewf types only, and ewf types need that racking. Another combination is rejected with the reason.

A minimal scene of two trackers and a tank, one comment per key. JSON has no comments: remove them before sending.

{
  "version": 2,                              // always 2
  "types": [{"id": "trk", "kind": "sat",     // sat tracker, gft fixed rack or ewf ridge
             "length": 60, "width": 4.3,     // along the axis / across it
             "modules": 84, "strings": 3}],  // modules weight the blend
  "placements": [                            // one per device
    {"id": "t1", "type": "trk", "x": 0, "y": 0, "z": 2,    // centre: x east, y north, z the axis height
     "azimuth_deg": 180, "tilt_deg": 0, "roll_deg": 0},     // 180 for a north-south axis
    {"id": "t2", "type": "trk", "x": 7, "y": 0, "z": 2.3,  // 7 units east: the pitch (GCR 4.3 / 7)
     "azimuth_deg": 180, "tilt_deg": 0, "roll_deg": 0}],
  "objects": [                               // prism, wall, tree_line, cylinder
    {"id": "tank", "kind": "cylinder", "x": 20, "y": -15, "z": 0, "radius": 3, "height": 8}],
  "outlines": []                             // drawn polygons, optional; never shade
}

The frame and origin blocks are optional (see the frame page).

References

1. Appelbaum & Bany 1979, Shadow effect of adjacent solar collectors in large scale systems, Solar Energy 23(6) 497–507
2. Heisler 1986, Effects of individual trees on the solar radiation climate of small buildings, Urban Ecology 9(3–4) 337–359

API

scene