Skip to content

PVCollada file format

The PVCollada file format is an open-source exchange format to describe 3D PV scenes. It is developed openly as a community effort, and its full specification is maintained in the PVCollada GitHub repository, accessible from the PVCollada website.

Two versions of the format exist:

  • PVCollada 2.0 (.pvc2 / .pvz2 files) is the current version and the recommended format for any new integration.
  • PVCollada 1.4.1 (.pvc files) is the original, legacy version.

PVCollada 2.0

PVCollada 2.0 files use the .pvc2 extension. A zipped PVCollada 2.0 file uses the .pvz2 extension.

The format is based on the COLLADA 1.5 format (full specifications available on the Khronos group website). A PVCollada 2.0 document is a valid COLLADA 1.5 document: all PV-specific information (physical components, electrical and mechanical relationships) is carried in standard COLLADA <extra> elements, so the file remains readable by any COLLADA-compliant tool.

The complete PVCollada 2.0 specification, schemas and examples are available in the PVCollada GitHub repository, accessible from the PVCollada website.

Support in PVsyst

PVsyst can import .pvc2 and .pvz2 files since version 8.1.5. PVsyst currently only imports the PVCollada 2.0 format, it does not export it.

The import currently supports:

  • PV objects (<instance_table>, <instance_tracker>): PV tables and trackers are imported with their full parametrization: geometry, insets, module orientation, number of module rows and columns, row and column spacing, gaps, posts, nominal azimuth and tilt, rotation limits for trackers, etc.
  • Electrical objects (<instance_inverter3d>, <instance_combiner_ac3d>, <instance_combiner_dc3d>, <instance_optimizer3d>, <instance_transformer3d>, <instance_cable3d>): electrical objects are imported. If they were not specifically named in the PVCollada 2.0 file, they are named accordingly in the PVsyst 3D scene (Inverter #1, Transformer #2, etc.).
  • Terrain (<instance_terrain>): terrain meshes are imported as ground objects.
  • Shading objects: any other geometry is imported as a generic shading object.
  • Components (<module>, <inverter>, etc.): component definitions, including the PVsyst extensions for module (PAN) and inverter (OND) data, are read and used for consistency checking.
  • Metadata: scene metadata (<longitude>, <latitude>, <altitude>, etc.) are read and used for consistency checking.

The consistency checks compare the content of the PVCollada 2.0 file against the project definition in PVsyst (distance to the project site, compatibility with the module and inverter selected in the system definition), and verify the internal coherence of the scene itself (for example, that laying out the given number of module rows and columns with the specified module size, insets and spacing results in a table size matching the geometry of the 3D object).

The following is not yet supported:

  • Circuit: the electrical circuit description is currently ignored by the import but is next on our agenda.

Sample PVCollada 2.0 files can be found in the PVCollada GitHub repository, accessible from the PVCollada website.

The PVCollada 2.0 parser will keep being improved in future PVsyst versions, to read and import more and more parts of the format.

PVCollada 1.4.1 (legacy)

PVCollada 1.4.1 is the original version of the format, created by the PVsyst team in collaboration with the PVCase team. PVCollada 1.4.1 files use the .pvc extension. They can be imported into PVsyst since version 7.0.

The format is based on a modified version of the COLLADA 1.4.1 schema (full specifications available on the Khronos group website). Because of these modifications, a PVCollada 1.4.1 document is not a valid COLLADA document. This limitation is one of the reasons that led to the creation of PVCollada 2.0, which should be preferred for any new integration.

Format description

Extension of the <mesh> tags

The <mesh> tags can contain an additional child element from the following ones :

  • frame_parameters
  • tracker_parameters

It must contain only one of these and not the two simultaneously.

Adding one of these tags to the mesh will define it as a PV mesh and each of its faces will be converted to such in PVsyst after the import.

<frame_parameters>

This element describes a fixed-tilt table, it must contain the following child elements :

  • module_width : INTEGER type, millimeters, describes the width of a module contained in the table
  • module_height : INTEGER type, millimeters, describes the height of a module contained in the table
  • module_x_spacing : FLOAT type, millimeters, describes the horizontal spacing between modules contained in the table
  • module_y_spacing : FLOAT type, millimeters, describes the vertical spacing between modules contained in the table
  • module_manufacturer : STRING type, describes the name of the module manufacturer
  • module_name : STRING type, describes the name of the module

<tracker_parameters>

This element describes a tracker, it must contain the following child elements :

  • module_width : INTEGER type, millimeters, describes the width of a module contained in the table
  • module_height : INTEGER type, millimeters, describes the height of a module contained in the table
  • module_x_spacing : FLOAT type, millimeters, describes the horizontal spacing between modules contained in the table
  • module_y_spacing : FLOAT type, millimeters, describes the vertical spacing between modules contained in the table
  • module_manufacturer : STRING type, describes the name of the module manufacturer
  • module_name : STRING type, describes the name of the module
  • tracker_type : STRING type enumeration ("single_axis_trackers", "dual_axis_trackers"), describes the kind of trackers
  • axis_vertices : this element must contain two child elements of type <float_array> with a length of 3, describing the global coordinates of the two axis points
  • min_phi : FLOAT type (between -90 and 90), degrees, describes the minimum E-W tracking rotation angle
  • max_phi : FLOAT type (between -90 and 90), degrees, describes the maximum E-W tracking rotation angle
  • min_theta : FLOAT type (between -90 and 90), degrees, describes the minimum N-S tracking rotation angle
  • max_theta : FLOAT type (between -90 and 90), degrees, describes the maximum N-S tracking rotation angle

Sample PVC files can be found in the DataRO/PVsyst8.1_Data/Userdata subfolder of the PVsyst installation folder.