Archicad 29 C++ API
Loading...
Searching...
No Matches
Classes | Enumerations | Functions
Geolocation

Functions related to the manipulation of and accessing the Project Location data and Archicad's related functionalities. More...

Classes

struct  API_Point
 Pixel data. More...
 
struct  API_Coord
 A pair of Cartesian (real) coordinates. More...
 
struct  API_Coord3D
 Real (Cartesian) 3D coordinates of a three-dimensional space. More...
 
struct  API_PlaceInfo
 The current location, date and sun parameters. More...
 
struct  API_GeoReferenceData
 Coordinate Reference System and Map Conversion parameters of the Geo Location of the project. More...
 
struct  API_GeoLocation
 Geo Location data of the project. More...
 

Enumerations

enum class  API_LongLatUnitID { API_LongLatUnitID::APILongLatUnit_DecimalDegree , API_LongLatUnitID::APILongLatUnit_DegreeMinSec }
 Possible values for longitude and latitude unit preferences. More...
 
enum  API_NorthUnitID { APINorthUnit_DecimalDegree , APINorthUnit_DegreeMinSec }
 typedef enum { APINorthUnit_DecimalDegree, APINorthUnit_DegreeMinSec } API_NorthUnitID ;
 
enum  API_AltitudeUnitID { APIAltitudeUnit_Meter , APIAltitudeUnit_DecFoot }
 typedef enum { APIAltitudeUnit_Meter, APIAltitudeUnit_DecFoot } API_AltitudeUnitID ;
 

Functions

GSErrCode ACAPI_GeoLocation_GetSunSets (API_SunInfo *sunInfo)
 Returns information on sun parameters.
 
GSErrCode ACAPI_GeoLocation_GetPlaceSets (API_PlaceInfo *placeInfo)
 Returns information on location parameters.
 
GSErrCode ACAPI_GeoLocation_CanChangePlaceSets (bool *withDialog)
 May the current user change the place settings now?
 
GSErrCode ACAPI_GeoLocation_ChangePlaceSets (API_PlaceInfo *placeInfo)
 Changes the place settings.
 
GSErrCode ACAPI_GeoLocation_GetGeoLocation (API_GeoLocation *apiGeoLocation)
 Returns the Location settings of the project.
 
GSErrCode ACAPI_GeoLocation_SetGeoLocation (API_GeoLocation *apiGeoLocation)
 Modifies the Location settings of the project.
 
GSErrCode ACAPI_GeoLocation_CalcSunOnPlace (API_PlaceInfo *placeInfo)
 Calculates the sun position in a given place.
 

Detailed Description

Functions related to the manipulation of and accessing the Project Location data and Archicad's related functionalities.

Enumeration Type Documentation

◆ API_LongLatUnitID

enum class API_LongLatUnitID
strong

Possible values for longitude and latitude unit preferences.

Since
Archicad 26
Enumerator
APILongLatUnit_DecimalDegree 

Show longitude and latitude in decimal degrees

APILongLatUnit_DegreeMinSec 

Show longitude and latitude in degrees, minutes, seconds

Function Documentation

◆ ACAPI_GeoLocation_CalcSunOnPlace()

GSErrCode ACAPI_GeoLocation_CalcSunOnPlace ( API_PlaceInfo * placeInfo)

Calculates the sun position in a given place.

Since
Archicad 26
Parameters
placeInfo[in/out] Parameters of the sun place.
API_PlaceInfo
longitude required, longitude
latitude required, latitude
sumTime required, daylight saving on/off
year required, year
month required, month
day required, day
hour required, hour
minute required, minute
second required, second
time zone required, time zone in minutes
north required, north direction
sunAngXY out, the sun angle
sunAngZ out, the sun angle
Returns
  • NoError - The function has completed with success.
  • APIERR_NOPLAN - no open project
  • APIERR_BADPARS - placeInfo is nullptr or contains invalid data
Remarks
This function is used get the sun angles to in a custom place. The sun angles are calculated in a given place and on a certain day and time. The calculated angles are returned in the sunAngXY and sunAngZ fields of the structure. Refer to the ACAPI_GeoLocation_GetPlaceSets function to get the actual location and date parameters.
Example
API_PlaceInfo placeInfo {};
GSErrCode err;
placeInfo.longitude = 47.497913;
placeInfo.latitude = 19.040236;
placeInfo.sumTime = false; /* winter time */
placeInfo.year= 2001;
placeInfo.month = 11;
placeInfo.day = 11;
placeInfo.hour= 10;
placeInfo.minute = 7;
placeInfo.second = 12;
placeInfo.timeZoneInMinutes = 60;
placeInfo.north = PI / 2; /* up direction */
err = ACAPI_GeoLocation_CalcSunOnPlace (&placeInfo);

◆ ACAPI_GeoLocation_CanChangePlaceSets()

GSErrCode ACAPI_GeoLocation_CanChangePlaceSets ( bool * withDialog)

May the current user change the place settings now?

Parameters
withDialog[in] If the user don't have permisson to change the place settings now, then the Location Dialog will open if this parameter is true, otherwise it will just return whether the user can or can not change the place settings now. This parameter is optional; if you pass nullptr, it defaults to true.
Returns
  • NoError - The user is allowed to change the place settings.
  • APIERR_NOTEDITABLE - The user is not allowed to change the place settings.
Example
bool withDialog = false;
ACAPI_GeoLocation_CanChangePlaceSets (&withDialog);

◆ ACAPI_GeoLocation_ChangePlaceSets()

GSErrCode ACAPI_GeoLocation_ChangePlaceSets ( API_PlaceInfo * placeInfo)

Changes the place settings.

Since
Archicad 26
Parameters
placeInfo[in] This structure holds the parameters of the place.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - placeInfo is nullptr or contains invalid data.
  • APIERR_NOPLAN - No open project.
Remarks
This function is used to set/change the current place, date, time and north direction parameters of the plan. The sun angles are calculated in the given place and on the given day and time. The calculated angles are returned in the sunAngXY and sunAngZ fields of the API_PlaceInfo structure. Please refer to the ACAPI_GeoLocation_GetPlaceSets function for calculating the sun parameters at a custom place on a certain date.
Example
API_PlaceInfo placeInfo {};
ACAPI_GeoLocation_GetPlaceSets (&placeInfo);
placeInfo.north += PI/2;
ACAPI_GeoLocation_ChangePlaceSets (&placeInfo);

◆ ACAPI_GeoLocation_GetGeoLocation()

GSErrCode ACAPI_GeoLocation_GetGeoLocation ( API_GeoLocation * apiGeoLocation)

Returns the Location settings of the project.

Since
Archicad 25
Parameters
apiGeoLocation[out] Location data associated with the project
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - apiGeoLocation is nullptr
Remarks
This function returns the Location settings of the project.
Example
API_GeoLocation geoLocation;
ACAPI_GeoLocation_GetGeoLocation (&geoLocation);
geoLocation.surveyPointPosition.x = -300000;
geoLocation.surveyPointPosition.y = -100000;
geoLocation.surveyPointPosition.z = 100;
ACAPI_GeoLocation_SetGeoLocation (&geoLocation); // sets the position of the survey point

◆ ACAPI_GeoLocation_GetPlaceSets()

GSErrCode ACAPI_GeoLocation_GetPlaceSets ( API_PlaceInfo * placeInfo)

Returns information on location parameters.

Since
Archicad 26
Parameters
placeInfo[out] Parameters of the place.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - placeInfo is nullptr.
  • APIERR_NOPLAN - No open project.
Remarks
This function is used to get the current place, date, time, and sun information. These data can be set in the Sun Settings dialog. Refer to the ACAPI_GeoLocation_CalcSunOnPlace function to calculate the sun parameters on a custom place and date; Refer to the ACAPI_GeoLocation_ChangePlaceSets function to set the current settings.
Example
API_PlaceInfo placeInfo {};
return ACAPI_GeoLocation_GetPlaceSets (&placeInfo);

◆ ACAPI_GeoLocation_GetSunSets()

GSErrCode ACAPI_GeoLocation_GetSunSets ( API_SunInfo * sunInfo)

Returns information on sun parameters.

Parameters
sunInfo[out] Parameters of the sun.
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - sunInfo is nullptr.
  • APIERR_NOPLAN - No open project.
Remarks
This function is used to get information on sunlight parameters. These parameters are sophisticated sunlight for photorendering.
Example
API_SunInfo sunInfo {};
return ACAPI_GeoLocation_GetSunSets (&sunInfo);

◆ ACAPI_GeoLocation_SetGeoLocation()

GSErrCode ACAPI_GeoLocation_SetGeoLocation ( API_GeoLocation * apiGeoLocation)

Modifies the Location settings of the project.

Since
Archicad 25
Parameters
apiGeoLocation[in] the Location settings associated with the project
Returns
  • NoError - The function has completed with success.
  • APIERR_BADPARS - apiGeoLocation is nullptr
  • APIERR_NOTEDITABLE - The Location settings cannot be modified in Teamwork unless it is reserved by the current user.
Remarks
This function sets the Location settings of the project. The ACAPI_GeoLocation_SetGeoLocation function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.
Example
API_GeoLocation geoLocation;
ACAPI_GeoLocation_GetGeoLocation (&geoLocation);
geoLocation.surveyPointPosition.x = -300000;
geoLocation.surveyPointPosition.y = -100000;
geoLocation.surveyPointPosition.z = 100;
ACAPI_GeoLocation_SetGeoLocation (&geoLocation); // sets the position of the survey point