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	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 ;
enum class	API_LongLatUnitID { APILongLatUnit_DecimalDegree , APILongLatUnit_DegreeMinSec }
	enum class API_LongLatUnitID { APILongLatUnit_DecimalDegree, APILongLatUnit_DegreeMinSec } ; More...

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

enum class API_LongLatUnitID { APILongLatUnit_DecimalDegree, APILongLatUnit_DegreeMinSec } ;

Since

Archicad 26

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_Goodies (APIAny_CalcSunOnPlaceID, &placeInfo, nullptr);

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_Environment (APIEnv_CanChangePlaceSetsID, &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 = {};
GSErrCode      err;
 
err = ACAPI_Environment (APIEnv_GetPlaceSetsID, &placeInfo, nullptr);
placeInfo.north += PI/2;
err = ACAPI_Environment (APIEnv_ChangePlaceSetsID, &placeInfo, nullptr);

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

See the example of the APIEnv_SetGeoLocationID
function.

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 = {};
GSErrCode      err;
 
err = ACAPI_Environment (APIEnv_GetPlaceSetsID, &placeInfo, nullptr);

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 = {};
GSErrCode    err;
 
err = ACAPI_Environment (APIEnv_GetSunSetsID, &sunInfo, nullptr);

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_Environment (APIEnv_GetGeoLocationID, &geoLocation);
geoLocation.surveyPointPosition.x = -300000;
geoLocation.surveyPointPosition.y = -100000;
geoLocation.surveyPointPosition.z = 100;
ACAPI_Environment (APIEnv_SetGeoLocationID, &geoLocation);  // sets the position of the survey point