/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

#ifndef _IFC_API_UTILS_H
#define _IFC_API_UTILS_H

#include "IfcBuildOptions.h"
#include "daiObjectId.h"

#include "TD_PackPush.h"

class OdIfcFile;

/** \details 
Contains declarations related to working with IFC file content.
*/
namespace OdIfc {

  class OdIfcInstance;
  
  /** \details
  Contains declarations related to working with IFC files content.
  */
  namespace Utils
  {
    /** \details
    Assigns a generated global identifier to the "GlobalId" attribute  of an entity derived from an IfcRoot object.
    \param inst [in] A raw pointer to the IFC entity instance.
    \returns true if the attribute "GlobalId" was successfully assigned; otherwise the method returns false.
    */
    bool IFCCORE_EXPORT assignGlobalId(OdIfcInstance *inst);

    /** \details
    Retrieves identifiers (represented with the <exref target="../tifc_api_cpp/OdDAIObjectIds.html">OdDAIObjectIds</exref> object) 
    of default IfcGeometricRepresentationContext instances, 
    which are necessary to get the geometrical representation of a model of the specified IFC file.
    \param pIfcFile [in] A raw pointer to an <exref target="../tifc_api_cpp/OdIfcFile.html">OdIfcFile</exref> object that keeps the IFC model.
    \param onlyBody [in] A flag that determines that only sub-contexts with the &quot;Body&quot; identifiers are selected (if it is equal to true). 
    \returns 
     An <exref target="../tifc_api_cpp/OdDAIObjectIds.html">array of OdDAIObjectId</exref> instances, which contain identifiers 
     that refer to geometric representation context objects; if nothing was selected, the method returns an empty array.
    \remarks
     Earlier IFC versions as IFC2X2 are supported by finding users of contexts.
    */
    OdDAIObjectIds IFCCORE_EXPORT getDefaultRepresentationContextsSelection(const OdIfcFile *pIfcFile, bool onlyBody = true);

    /** \details
    Retrieves identifiers (represented with the <exref target="../tifc_api_cpp/OdDAIObjectIds.html">OdDAIObjectIds</exref> object) 
    of all IfcGeometricRepresentationContext instances in a model of the specified IFC file.
    \param pIfcFile [in] A raw pointer to an <exref target="../tifc_api_cpp/OdIfcFile.html">OdIfcFile</exref> object that keeps the IFC model.
    \returns 
     An <exref target="../tifc_api_cpp/OdDAIObjectIds.html">array of OdDAIObjectId</exref> instances, which contain identifiers 
     that refer to geometric representation context objects; if nothing was selected, the method returns an empty array.
    */
    OdDAIObjectIds IFCCORE_EXPORT getAllRepresentationContexts(const OdIfcFile *pIfcFile);

    /** \details
    Retrieves identifier of parent container for IfcElement.
    \param instance [in] A pointer to IFC entity instance.
    \returns The <exref target="../tifc_api_cpp/OdDAIObjectId.html">object identifier</exref> of the parent entity  or the <exref target="../tifc_api_cpp/OdDAIObjectId__kNullHandle.html">kNullHandle</exref> value otherwise.
    */
    OdDAIObjectId IFCCORE_EXPORT getParentContainer(const OdDAI::ApplicationInstancePtr instance);

    /** \details
    Retrieves all identifiers of IfcElement entities that are "inside" (are descendants in IfcRelAggregates/IfcRelContainedInSpatialStructure relationship) current IfcElement instance.
    \param instance [in] A pointer to IFC entity instance.
    \returns
    An <exref target="../tifc_api_cpp/OdDAIObjectIds.html">array of OdDAIObjectId</exref> instances, which contain identifiers
    that refer to nested items; if nothing was selected, the method returns an empty array.
    */
    OdDAIObjectIds IFCCORE_EXPORT getNestedSubitems(const OdDAI::ApplicationInstancePtr instance);

    /** \details
    Retrieves identifier of parent entity in relation structure (containedinstructure/decomposes) for IfcElement.
    \param instance [in] A pointer to IFC entity instance.
    \returns The <exref target="../tifc_api_cpp/OdDAIObjectId.html">object identifier</exref> of the parent entity in relation structure or the <exref target="../tifc_api_cpp/OdDAIObjectId__kNullHandle.html">kNullHandle</exref> value otherwise.
    */
    OdDAIObjectId IFCCORE_EXPORT getParentItem(const OdDAI::ApplicationInstancePtr instance);

    /** \details
    Retrieves subitems identifiers of current IfcElement based on decompose, containment or voids relationship.
    \param instance [in] A pointer to IFC application instance.
    \returns OdDAIObjectIds, array of OdDAIObjectId instances, which contain subitems identifiers or empty array otherwise.
    */
    OdDAIObjectIds IFCCORE_EXPORT getSubItems(const OdDAI::ApplicationInstancePtr instance);

    /** \details
    Retrieves subitems identifiers of current IfcElement on decompose, containment or voids relationship with specified type.
    \param instance [in] A pointer to IFC application instance.
    \param subItemType [in] OdAnsiString that contains subitem types to extract.
    \returns OdDAIObjectIds, array of OdDAIObjectId instances, which contain subitems identifiers or empty array otherwise.
    */
    OdDAIObjectIds IFCCORE_EXPORT getSubItemsByType(const OdDAI::ApplicationInstancePtr instance, const OdAnsiString& subItemType);

    /** \details
    Retrieves identifiers of representation items for specified products collection.
    \param products [in] OdDAIObjectIds as collection of products to find representation items for.
    \returns OdDAIObjectIds, array of OdDAIObjectId instances, which contain representation items or empty array otherwise.
    */
    OdDAIObjectIds IFCCORE_EXPORT getProductsRepresentations(const OdDAIObjectIds& products);

    /** \details
    Retrieves identifiers of products which representation items are assigned for specified layers collection.
    \param layers [in] OdDAIObjectIds as collection of IfcPresentationLayerAssignment and its subclasses to find representation items for.
    \returns OdDAIObjectIds, array of OdDAIObjectId instances, which contain products items or empty array otherwise.
    */
    OdDAIObjectIds IFCCORE_EXPORT getPresentationLayerAssignmentProducts(OdDAIObjectIds& layers);

    /** \details
    Retrieves identifiers of layers items for specified product.
    \param product [in] OdDAIObjectId as product identifier to find layers items for.
    \returns OdDAIObjectIds, array of OdDAIObjectId instances, which contains layers items as IfcPresentationLayerAssignments and its subclasses or empty array otherwise.
    */
    OdDAIObjectIds IFCCORE_EXPORT getPresentationLayers(const OdDAIObjectId& product);

    /** \details
    Retrieves scale factor for unit prefix.
    \param unitPrefix [in] Unit prefix string value.
    \returns Double value of scale factor for unit prefix.
    */
    double IFCCORE_EXPORT getPrefixUnitScale(const OdAnsiString& unitPrefix);


    /** \details
    Retrieves scale factor for conversion based unit.
    \param namedUnit [in] OdDAIObjectId as conversion based unit identifier to extract scale factor for.
    \param unitType [in] Unit prefix string value from allowed unit types of IfcNamedUnit.
    \param targetFactor [in] scale factor of target unit based on prefix.
    \returns Double value of scale factor for unit.
    */
    double IFCCORE_EXPORT getConversionUnitScaleFactor(const OdDAIObjectId& namedUnit, const OdAnsiString& unitType, double targetFactor = 1.0f);

    /** \details
    Retrieves scale factor for SI unit.
    \param namedUnit [in] OdDAIObjectId as SI unit identifier to extract scale factor for.
    \param unitType [in] Unit type string value from allowed unit types of IfcNamedUnit.
    \param unitName [in] Unit name string value from allowed unit name of IfcSiUnit.
    \returns Double value of scale factor for unit.
    */
    double IFCCORE_EXPORT getSiUnitScaleFactor(const OdDAIObjectId& namedUnit, const OdAnsiString& unitType = "LENGTHUNIT", const OdAnsiString& unitName = "METRE");

    /** \details
    Retrieves a scale factor for the prefix of IfcSiUnit instance.
    \param namedUnit [in] OdDAIObjectId of SI unit instance to extract scale factor for.
    \param unitType [in] Unit type string value from allowed unit types of IfcNamedUnit.
    \returns Double value of scale factor for unit prefix.
    */
    double IFCCORE_EXPORT getSiUnitPrefixScaleFactor(const OdDAIObjectId& siUnit, const char* unitType = "LENGTHUNIT");

    /** \details
    Retrieves a scale factor from IfcProject for the unit with needed type.
    \param projectId [in] OdDAIObjectId of IfcProject instance.
    \param unitTypeName [in] Unit type string value from unit types of IfcNamedUnit.
    \returns Double value of scale factor for unit type.
    */
    double IFCCORE_EXPORT getProjectsUnitConversionFactor(const OdDAIObjectId& projectId, const char* unitTypeName = "LENGTHUNIT");

    /** \details
    Retrieves approximate linear distance between two points on map from latitude / longitude.
    \param lat1 [in] Latitude of 1st point in degrees.
    \param lon1 [in] Longitude of 1st point in degrees.
    \param lat2 [in] Latitude of 2nd point in degrees.
    \param lon2 [in] Longitude of 2nd point in degrees.
    \returns Double value of distance.
    */
    double IFCCORE_EXPORT getDistanceBetweenMapPoints(const double& lat1, const double& lon1, const double& lat2, const double& lon2);
  }
}

#include "TD_PackPop.h"

#endif // _IFC_API_UTILS_H