SUModelRef Struct Reference

A SketchUp model. More...

#include <SketchUpAPI/model/model.h>

Related Functions
(Note that these are not member functions.)
enum SUResult	SUModelCreate (SUModelRef *model)
	Creates an empty model object for the purposes of writing a SketchUp document. This model object must be released with SUModelRelease(). More...
enum SUResult	SUModelCreateFromFile (SUModelRef *model, const char *file_path)
	Creates a model from a SketchUp file on local disk. This model object must be released with SUModelRelease(). More...
enum SUResult	SUModelCreateFromFileWithStatus (SUModelRef *model, const char *file_path, enum SUModelLoadStatus *status)
	Creates a model from a SketchUp file on local disk. This model object must be released with SUModelRelease(). More...
enum SUResult	SUModelCreateFromBuffer (SUModelRef *model, const unsigned char *buffer, size_t buffer_size)
	Creates a model from a SketchUp skp file buffer. This model object must be released with SUModelRelease(). More...
enum SUResult	SUModelCreateFromBufferWithStatus (SUModelRef *model, const unsigned char *buffer, size_t buffer_size, enum SUModelLoadStatus *status)
	Creates a model from a SketchUp skp file buffer. This model object must be released with SUModelRelease(). More...
enum SUResult	SUModelRelease (SUModelRef *model)
	Releases a model object and its associated resources. The root component of the model object and all its child objects must not be released explicitly. More...
enum SUResult	SUModelGetEntities (SUModelRef model, SUEntitiesRef *entities)
	Retrieves the root model entities. More...
enum SUResult	SUModelGetActiveEntities (SUModelRef model, SUEntitiesRef *entities)
	Retrieves the model entities of the active context (open group or component). More...
enum SUResult	SUModelGetActivePath (SUModelRef model, SUInstancePathRef *instance_path)
	Retrieves the instance path of the active context (open group or component). More...
enum SUResult	SUModelGetNumMaterials (SUModelRef model, size_t *count)
	Retrieves the number of materials in a model object. More...
enum SUResult	SUModelGetMaterials (SUModelRef model, size_t len, SUMaterialRef materials[], size_t *count)
	Retrieves all the materials associated with a model object. More...
enum SUResult	SUModelAddMaterials (SUModelRef model, size_t len, const SUMaterialRef materials[])
	Adds materials to a model object. Note that the materials cannot be already owned. More...
enum SUResult	SUModelGetNumComponentDefinitions (SUModelRef model, size_t *count)
	Retrieves the number of components associated with a model. More...
enum SUResult	SUModelGetComponentDefinitions (SUModelRef model, size_t len, SUComponentDefinitionRef definitions[], size_t *count)
	Retrieves the component definitions that define component instances but not groups. More...
enum SUResult	SUModelGetNumGroupDefinitions (SUModelRef model, size_t *count)
	Retrieves the number of component definitions that define groups. More...
enum SUResult	SUModelGetGroupDefinitions (SUModelRef model, size_t len, SUComponentDefinitionRef definitions[], size_t *count)
	Retrieves the component definitions that define groups. More...
enum SUResult	SUModelGetNumImageDefinitions (SUModelRef model, size_t *count)
	Retrieves the number of component definitions that define images. More...
enum SUResult	SUModelGetImageDefinitions (SUModelRef model, size_t len, SUComponentDefinitionRef definitions[], size_t *count)
	Retrieves the component definitions that define images. More...
enum SUResult	SUModelAddComponentDefinitions (SUModelRef model, size_t len, const SUComponentDefinitionRef components[])
	Adds component definitions to a model object. More...
enum SUResult	SUModelRemoveComponentDefinitions (SUModelRef model, size_t len, SUComponentDefinitionRef components[])
	Remove definitions of components, images, and groups from a model object. All component definitions, their geometry, and attached instances will be released. More...
enum SUResult	SUModelSaveToFile (SUModelRef model, const char *file_path)
	Saves the model to a file. More...
enum SUResult	SUModelSaveToFileWithVersion (SUModelRef model, const char *file_path, enum SUModelVersion version)
	Saves the model to a file using a specific SketchUp version format. More...
enum SUResult	SUModelGetCamera (SUModelRef model, SUCameraRef *camera)
	Retrieves the camera of a model object. The returned camera object points to model's internal camera. So it must not be released via SUCameraRelease(). More...
enum SUResult	SUModelSetCamera (SUModelRef model, SUCameraRef *camera)
	Sets the current camera of a model object. More...
enum SUResult	SUModelGetNumScenes (SUModelRef model, size_t *num_scenes)
	Retrieves the number of scene cameras of a model object. More...
enum SUResult	SUModelGetNumLayers (SUModelRef model, size_t *count)
	Retrieves the number of layers in a model object. More...
enum SUResult	SUModelGetLayers (SUModelRef model, size_t len, SULayerRef layers[], size_t *count)
	Retrieves the layers in a model object. More...
enum SUResult	SUModelAddLayers (SUModelRef model, size_t len, const SULayerRef layers[])
	Adds layer objects to a model object. More...
enum SUResult	SUModelGetDefaultLayer (SUModelRef model, SULayerRef *layer)
	Retrieves the default layer object of a model object. More...
enum SUResult	SUModelRemoveLayers (SUModelRef model, size_t len, SULayerRef layers[])
	Removes all layers provided in the array. The default layer cannot be removed. All entities on the deleted layers will be moved to the default layer. More...
enum SUResult	SUModelGetActiveLayer (SUModelRef model, SULayerRef *layer)
	Retrieves the active layer object of a model object. More...
enum SUResult	SUModelSetActiveLayer (SUModelRef model, SULayerRef layer)
	Sets the active layer object of a model object. More...
enum SUResult	SUModelGetVersion (SUModelRef model, int *major, int *minor, int *build)
	Retrieves the version of a model object. The version consists of three numbers: major version number, minor version number, and the build number. More...
enum SUResult	SUModelGetNumAttributeDictionaries (SUModelRef model, size_t *count)
	Retrieves the number of attribute dictionaries of a model object. More...
enum SUResult	SUModelGetAttributeDictionaries (SUModelRef model, size_t len, SUAttributeDictionaryRef dictionaries[], size_t *count)
	Retrieves the attribute dictionaries of a model object. More...
enum SUResult	SUModelGetAttributeDictionary (SUModelRef model, const char *name, SUAttributeDictionaryRef *dictionary)
	Retrieves the attribute dictionary of a model object that has the given name. If a dictionary with the given name does not exist, one is added to the model object. More...
enum SUResult	SUModelIsGeoReferenced (SUModelRef model, bool *is_geo_ref)
	Retrieves whether the model is georeferenced. More...
enum SUResult	SUModelGetLocation (SUModelRef model, SULocationRef *location)
	Retrieves the location information of a given model. More...
enum SUResult	SUModelGetStatistics (SUModelRef model, struct SUModelStatistics *statistics)
	Calculates the sum of all entities by type in the model. More...
enum SUResult	SUModelSetGeoReference (SUModelRef model, double latitude, double longitude, double altitude, bool is_z_value_centered, bool is_on_ocean_floor)
	Georeferences the model. More...
enum SUResult	SUModelGetRenderingOptions (SUModelRef model, SURenderingOptionsRef *rendering_options)
	Retrieves the rendering options of a model object. More...
enum SUResult	SUModelGetShadowInfo (SUModelRef model, SUShadowInfoRef *shadow_info)
	Retrieves the shadow info of a model object. More...
enum SUResult	SUModelGetOptionsManager (SUModelRef model, SUOptionsManagerRef *options_manager)
	Retrieves options manager associated with the model. More...
enum SUResult	SUModelGetNorthCorrection (SUModelRef model, double *north_correction)
	Retrieves the angle which will rotate the north direction to the y-axis for a given model. More...
enum SUResult	SUModelMergeCoplanarFaces (SUModelRef model)
	Merges all adjacent, coplanar faces in the model. More...
enum SUResult	SUModelGetScenes (SUModelRef model, size_t len, SUSceneRef scenes[], size_t *count)
	Retrieves all the scenes associated with a model object. More...
enum SUResult	SUModelGetSceneWithName (SUModelRef model, const char *name, SUSceneRef *scene)
	Retrieves the scenes with the given name associated with a model object. More...
enum SUResult	SUModelAddScenes (SUModelRef model, size_t len, const SUSceneRef scenes[])
	Adds scenes to a model object. More...
enum SUResult	SUModelAddScene (SUModelRef model, int index, SUSceneRef scene, int *out_index)
	Adds scenes to a model object. More...
enum SUResult	SUModelGetActiveScene (SUModelRef model, SUSceneRef *scene)
	Retrieves the active scene associated with a model object. More...
enum SUResult	SUModelSetActiveScene (SUModelRef model, SUSceneRef scene)
	Sets the provided scene as the active scene. More...
enum SUResult	SUModelAddMatchPhotoScene (SUModelRef model, const char *image_file, SUCameraRef camera, const char *scene_name, SUSceneRef *scene)
	Adds a single matched photo scene to a model object. More...
enum SUResult	SUModelGetName (SUModelRef model, SUStringRef *name)
	Retrieves the name of a model object. More...
enum SUResult	SUModelSetName (SUModelRef model, const char *name)
	Sets the name of a model object. More...
enum SUResult	SUModelGetPath (SUModelRef model, SUStringRef *path)
	Retrieves the file path of a model object. More...
enum SUResult	SUModelGetTitle (SUModelRef model, SUStringRef *title)
	Retrieves the title of a model object. More...
enum SUResult	SUModelGetDescription (SUModelRef model, SUStringRef *description)
	Retrieves the description of a model object. More...
enum SUResult	SUModelSetDescription (SUModelRef model, const char *description)
	Sets the description of a model object. More...
enum SUResult	SUModelGetUnits (SUModelRef model, enum SUModelUnits *units)
	Returns the units associated with the given model. More...
enum SUResult	SUModelGetClassifications (SUModelRef model, SUClassificationsRef *classifications)
	Retrieves the classifications of a model object. More...
enum SUResult	SUModelGetAxes (SUModelRef model, SUAxesRef *axes)
	Retrieves the axes of a model object. More...
enum SUResult	SUModelGetStyles (SUModelRef model, SUStylesRef *styles)
	Retrieves the styles of a model object. More...
enum SUResult	SUModelGetInstancePathByPid (SUModelRef model, SUStringRef pid_ref, SUInstancePathRef *instance_path_ref)
	Retrieves the instance path (including an entity) corresponding to a given persistent id. More...
enum SUResult	SUModelGetNumFonts (SUModelRef model, size_t *count)
	Retrieves the number of fonts in a model object. More...
enum SUResult	SUModelGetFonts (SUModelRef model, size_t len, SUFontRef fonts[], size_t *count)
	Retrieves all the fonts associated with a model object. More...
enum SUResult	SUModelGetDimensionStyle (SUModelRef model, SUDimensionStyleRef *style)
	Retrieves the dimension style associated with a model object. More...
enum SUResult	SUModelGetLengthFormatter (SUModelRef model, SULengthFormatterRef *formatter)
	Retrieves length formatter settings from the model. The given length formatter object must have been constructed using SULengthFormatterCreate(). It must be released using SULengthFormatterRelease(). More...
enum SUResult	SUModelGenerateUniqueMaterialName (SUModelRef model, const char *in_name, SUStringRef *out_name)
	Retrieves a unique material name from the model that is based on the provided one. If the provided name is unique it will be returned, otherwise any trailing indices will be replaced by a new index. More...
enum SUResult	SUModelFixErrors (SUModelRef model)
	Fixes any errors found in the given model. More...
enum SUResult	SUModelOrientFacesConsistently (SUModelRef model, bool recurse_components)
	Updates the faces in the model so that they are oriented consistently. More...
enum SUResult	SUModelGetLineStyles (SUModelRef model, SULineStylesRef *line_styles)
	Retrieves line styles from the model. More...
enum SUResult	SUModelLoadDefinition (SUModelRef model, const char *filename, SUComponentDefinitionRef *definition)
	Loads a component from a file. More...
enum SUResult	SUModelLoadDefinitionWithStatus (SUModelRef model, const char *filename, SUComponentDefinitionRef *definition, enum SUModelLoadStatus *status)
	Loads a component from a file. More...
enum SUResult	SUModelRemoveMaterials (SUModelRef model, size_t len, SUMaterialRef materials[])
	Removes all materials provided in the array. More...
enum SUResult	SUModelRemoveScenes (SUModelRef model, size_t len, SUSceneRef scenes[])
	Removes selected scenes from a model. More...
enum SUResult	SUModelGetNumAllMaterials (SUModelRef model, size_t *count)
	Retrieves the number of all the materials in a model including those belonging to SUImageRef and SULayerRef. More...
enum SUResult	SUModelGetAllMaterials (SUModelRef model, size_t len, SUMaterialRef materials[], size_t *count)
	Retrieves all the materials associated with a model object including those belonging to SUImageRef and SULayerRef. More...
enum SUResult	SUModelGetGuid (SUModelRef model, SUStringRef *guid)
	Retrieves the guid of a model object. More...
enum SUResult	SUModelGetLayersByPersistentIDs (SUModelRef model, size_t num_pids, const int64_t pids[], SULayerRef layers[])
	Retrieves layers by their persistent ids. The layers retrieved will be in the same order as to the peristent ids passed in. If a persistent id doesn't belong to a layer, then a SU_INVALID element will be returned along with SU_ERROR_PARTIAL_SUCCESS. More...
enum SUResult	SUModelIsDrawingElementVisible (SUModelRef model, SUInstancePathRef path, bool *visible)
	Reports whether the given SUDrawingElementRef in an SUInstancePathRef is visible given the model's rendering options. This will take into account "DrawHiddenGeometry" and "DrawHiddenObjects" to determine if the drawing element is visible in the viewport. More...
enum SUResult	SUModelGetEntitiesByPersistentIDs (SUModelRef model, size_t num_pids, const int64_t pids[], SUEntityRef entities[])
	Retrieves entities by their persistent ids. The entities retrieved will be in the same order as to the peristent ids passed in. If a persistent id doesn't belong to a entity, then a SU_INVALID element will be returned along with SU_ERROR_PARTIAL_SUCCESS. More...
enum SUResult	SUModelGetSelection (SUModelRef model, SUSelectionRef *selection)
	Retrieves the selection object for a model. More...
enum SUResult	SUModelGetNumLayerFolders (SUModelRef model, size_t *count)
	Gets the number of SULayerFolderRef objects owned by the given model. More...
enum SUResult	SUModelGetLayerFolders (SUModelRef model, size_t len, SULayerFolderRef *layer_folders, size_t *count)
	Gets the SULayerFolderRef objects that are owned by the given model. More...
enum SUResult	SUModelPurgeEmptyLayerFolders (SUModelRef model, size_t *count)
	Removes empty SULayerFolderRef objects from the model. More...
enum SUResult	SUModelAddLayerFolder (SUModelRef model, SULayerFolderRef layer_folder)
	Adds a SULayerFolderRef object to the model. More...
enum SUResult	SUModelPurgeUnusedLayers (SUModelRef model, size_t *count)
	Removes unused SULayerRef objects from the model. More...
enum SUResult	SUModelGetNumTopLevelLayers (SUModelRef model, size_t *count)
	Retrieves the number of layers in a model object that have not been added to any layer folder. More...
enum SUResult	SUModelGetTopLevelLayers (SUModelRef model, size_t len, SULayerRef layers[], size_t *count)
	Retrieves the layers in a model that have not been added to a layer folder. More...
enum SUResult	SUModelRemoveLayerFolders (SUModelRef model, size_t len, SULayerFolderRef layer_folders[])
	Removes all layer folders provided in the array. All children of the deleted layer folders will be moved to the parent of the deleted folder. More...
enum SUResult	SUModelGetEntitiesOfTypeByPersistentIDs (SUModelRef model, const uint32_t type_flags, const size_t num_pids, const int64_t pids[], SUEntityRef entities[])
	Retrieves entities of a given type by their persistent ids. The entities retrieved will be in the same order as to the peristent ids passed in. If a persistent id doesn't belong to an entity, then a SU_INVALID element will be returned along with SU_ERROR_PARTIAL_SUCCESS. More...
enum SUResult	SUModelGetBehavior (SUModelRef model, struct SUComponentBehavior *behavior)
	Retrieves the component behavior of a SketchUp model. More...
enum SUResult	SUModelSetBehavior (SUModelRef model, const struct SUComponentBehavior *behavior)
	Sets the component behavior of a SketchUp model. More...

Detailed Description

A SketchUp model.

Friends And Related Function Documentation

enum SUResult SUModelAddComponentDefinitions ( SUModelRef  model, size_t  len, const SUComponentDefinitionRef  components[]  )

related

Adds component definitions to a model object.

Parameters

[in]	model	The model object.
[in]	len	The number of component definitions to add.
[in]	components	The array of component definitions to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if components is NULL

enum SUResult SUModelAddLayerFolder ( SUModelRef  model, SULayerFolderRef  layer_folder  )

related

Adds a SULayerFolderRef object to the model.

Since

SketchUp 2021.0, API 9.0

Parameters

[in]	model	The model object.
[in]	layer_folder	The layer folder to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model or layer_folder is an invalid object
• SU_ERROR_INVALID_ARGUMENT if layer_folder fails to be added or is already part of the model.

enum SUResult SUModelAddLayers ( SUModelRef  model, size_t  len, const SULayerRef  layers[]  )

related

Adds layer objects to a model object.

Parameters

[in]	model	The model object.
[in]	len	The number of layers to add.
[in]	layers	The layers to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT of model is not a valid object
• SU_ERROR_INVALID_INPUT if any item in layers is not a valid object

enum SUResult SUModelAddMatchPhotoScene ( SUModelRef  model, const char *  image_file, SUCameraRef  camera, const char *  scene_name, SUSceneRef *  scene  )

related

Adds a single matched photo scene to a model object.

Since

SketchUp 2015, API 3.0

Parameters

[in]	model	The model object.
[in]	image_file	The full path of the image associated with this scene.
[in]	camera	The camera associated with this scene.
[in]	scene_name	The name of the scene to add.
[out]	scene	The scene object created.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model or camera is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if scene_name or image_file is NULL
• SU_ERROR_INVALID_OUTPUT if scene is NULL
• SU_ERROR_GENERIC if image_file is invalid or not found

enum SUResult SUModelAddMaterials ( SUModelRef  model, size_t  len, const SUMaterialRef  materials[]  )

related

Adds materials to a model object. Note that the materials cannot be already owned.

Parameters

[in]	model	The model object.
[in]	len	The number of material objects to add.
[in]	materials	The array of material objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if materials is NULL
• SU_ERROR_PARTIAL_SUCCESS if any of the materials are already owned

enum SUResult SUModelAddScene ( SUModelRef  model, int  index, SUSceneRef  scene, int *  out_index  )

related

Adds scenes to a model object.

Warning

Breaking Change: The behavior of SUModelAddScene changed in SketchUp SDK 2018 API 6.0 to return SU_ERROR_INVALID_ARGUMENT if the given scene name already exists in the model.

Parameters

[in]	model	The model object.
[in]	index	Where in the list to add the scene. -1 to place at the end.
[in]	scene	The scene object to add.
[out]	out_index	The index that the scene was added at.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model or scene are not a valid object
• SU_ERROR_INVALID_ARGUMENT if a scene with the same name already exists

enum SUResult SUModelAddScenes ( SUModelRef  model, size_t  len, const SUSceneRef  scenes[]  )

related

Adds scenes to a model object.

Warning

Breaking Change: The behavior of SUModelAddScenes changed in SketchUp SDK 2018 API 6.0 to return SU_ERROR_INVALID_ARGUMENT if at least one scene name already exists in the model or if there are duplicated names in the scenes array.

Parameters

[in]	model	The model object.
[in]	len	The number of scene objects to add.
[in]	scenes	The array of scene objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if scenes is NULL
• SU_ERROR_INVALID_ARGUMENT if the names of the given scenes are not unique among themselves or among existing scenes

enum SUResult SUModelCreate ( SUModelRef *  model )

related

Creates an empty model object for the purposes of writing a SketchUp document. This model object must be released with SUModelRelease().

Parameters

[out]

model

The model object created.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_OUTPUT if model is NULL
• SU_ERROR_OVERWRITE_VALID if model is already a valid object

enum SUResult SUModelCreateFromBuffer ( SUModelRef *  model, const unsigned char *  buffer, size_t  buffer_size  )

related

Creates a model from a SketchUp skp file buffer. This model object must be released with SUModelRelease().

Since

SketchUp 2017 M2, API 5.2

Deprecated:

This method will be removed in SketchUp 2022.0. It is replaced by SUModelCreateFromBufferWithStatus() which can read models saved by newer versions of SketchUp.

Parameters

[out]	model	The model object created.
[in]	buffer	The SketchUp file buffer.
[in]	buffer_size	The SketchUp file buffer size.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if buffer is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if model is NULL
• SU_ERROR_OVERWRITE_VALID if model is already a valid object
• SU_ERROR_SERIALIZATION if an error occurs during reading of the file
• SU_ERROR_MODEL_INVALID if the file specified by buffer is an invalid model.
• SU_ERROR_MODEL_VERSION if the model buffer has a newer version than is supported by the current build of the SDK.

enum SUResult SUModelCreateFromBufferWithStatus ( SUModelRef *  model, const unsigned char *  buffer, size_t  buffer_size, enum SUModelLoadStatus *  status  )

related

Creates a model from a SketchUp skp file buffer. This model object must be released with SUModelRelease().

Since

SketchUp 2021, API 9.0

Note

As of SketchUp 2021.0, SketchUp can open .skp files created with newer versions of SketchUp. However, opening newer versions with an older SDK might omit model data. Use the load status value to check if the file was created with a newer version of SketchUp.

Warning

When reading a file created with a newer version of SketchUp, you may lose data if you write over the same file.

Parameters

[out]	model	The model object created.
[in]	buffer	The SketchUp file buffer.
[in]	buffer_size	The SketchUp file buffer size.
[out]	status	Returns additional information on the status of a successful operation. Valid when the return value is SU_ERROR_NONE.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if buffer is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if model is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if status is NULL
• SU_ERROR_OVERWRITE_VALID if model is already a valid object
• SU_ERROR_SERIALIZATION if an error occurs during reading of the file
• SU_ERROR_MODEL_INVALID if the file specified by buffer is an invalid model.
• SU_ERROR_MODEL_VERSION if the model buffer has a newer version than is supported by the current build of the SDK.

enum SUResult SUModelCreateFromFile ( SUModelRef *  model, const char *  file_path  )

related

Creates a model from a SketchUp file on local disk. This model object must be released with SUModelRelease().

Deprecated:

This method will be removed in SketchUp 2022.0. It is replaced by SUModelCreateFromFileWithStatus() which can read models saved by newer versions of SketchUp.

Parameters

[out]	model	The model object created.
[in]	file_path	The source file path of the SketchUp file. Assumed to be UTF-8 encoded.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if model is NULL
• SU_ERROR_OVERWRITE_VALID if model is already a valid object
• SU_ERROR_SERIALIZATION if an error occurs during reading of the file
• SU_ERROR_MODEL_INVALID if the file specified by file_path is an invalid model. (since SketchUp 2014, API 2.0)
• SU_ERROR_MODEL_VERSION if the model file has a newer version than is supported by the current build of the SDK. (since SketchUp 2014, API 2.0)

enum SUResult SUModelCreateFromFileWithStatus ( SUModelRef *  model, const char *  file_path, enum SUModelLoadStatus *  status  )

related

Creates a model from a SketchUp file on local disk. This model object must be released with SUModelRelease().

Since

SketchUp 2021, API 9.0

Note

As of SketchUp 2021.0, SketchUp can open .skp files created with newer versions of SketchUp. However, opening newer versions with an older SDK might omit model data. Use the load status value to check if the file was created with a newer version of SketchUp.

Warning

When reading a file created with a newer version of SketchUp, you may lose data if you write over the same file.

Parameters

[out]	model	The model object created.
[in]	file_path	The source file path of the SketchUp file. Assumed to be UTF-8 encoded.
[out]	status	Returns additional information on the status of a successful operation. Valid when the return value is SU_ERROR_NONE.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if model is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if status is NULL
• SU_ERROR_OVERWRITE_VALID if model is already a valid object
• SU_ERROR_SERIALIZATION if an error occurs during reading of the file
• SU_ERROR_MODEL_INVALID if the file specified by file_path is an invalid model.
• SU_ERROR_MODEL_VERSION if the model file has a newer version than is supported by the current build of the SDK.

enum SUResult SUModelFixErrors ( SUModelRef  model )

related

Fixes any errors found in the given model.

Since

SketchUp 2018, API 6.0

Parameters

[in]

model

The model object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object

enum SUResult SUModelGenerateUniqueMaterialName ( SUModelRef  model, const char *  in_name, SUStringRef *  out_name  )

related

Retrieves a unique material name from the model that is based on the provided one. If the provided name is unique it will be returned, otherwise any trailing indices will be replaced by a new index.

Since

SketchUp 2018, API 6.0

Parameters

[in]	model	The model object.
[in]	in_name	The suggested name.
[out]	out_name	The returned name.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if in_name is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if out_name is NULL
• SU_ERROR_INVALID_OUTPUT if out_name does not point to a valid SUStringRef object

enum SUResult SUModelGetActiveEntities ( SUModelRef  model, SUEntitiesRef *  entities  )

related

Retrieves the model entities of the active context (open group or component).

Since

SketchUp 2020.2, API 8.2

Parameters

[in]	model	The model object.
[out]	entities	The entities retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if entities is NULL

enum SUResult SUModelGetActiveLayer ( SUModelRef  model, SULayerRef *  layer  )

related

Retrieves the active layer object of a model object.

Since

SketchUp 2020, API 8.0

Parameters

[in]	model	The model object.
[out]	layer	The layer object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if layer is NULL

enum SUResult SUModelGetActivePath ( SUModelRef  model, SUInstancePathRef *  instance_path  )

related

Retrieves the instance path of the active context (open group or component).

Note

This method only works from within the SketchUp application.

Parameters

[in]	model	The model object.
[out]	instance_path	The instance path retrieved. This must be released to avoid memory leak.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if instance_path is NULL
• SU_ERROR_OVERWRITE_VALID if instance_path is already a valid object
• SU_ERROR_NO_DATA if there is no active path open.
• SU_ERROR_NO_DATA if this isn't called from within SketchUp

enum SUResult SUModelGetActiveScene ( SUModelRef  model, SUSceneRef *  scene  )

related

Retrieves the active scene associated with a model object.

Since

SketchUp 2016, API 4.0

Parameters

[in]	model	The model object.
[out]	scene	The scene object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if scene is NULL
• SU_ERROR_OVERWRITE_VALID if scene is already a valid object
• SU_ERROR_NO_DATA if there is no active scene to retrieve

enum SUResult SUModelGetAllMaterials ( SUModelRef  model, size_t  len, SUMaterialRef  materials[], size_t *  count  )

related

Retrieves all the materials associated with a model object including those belonging to SUImageRef and SULayerRef.

Warning

Materials from SUImageRef and SULayerRef should not be applied to any other entity in the model. They are uniquely owned by the image or layer.

Since

SketchUp 2019.2, API 7.1

Parameters

[in]	model	The model object.
[in]	len	The number of material objects to retrieve.
[out]	materials	The material objects retrieved.
[out]	count	The number of material objects retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if materials or count is NULL

enum SUResult SUModelGetAttributeDictionaries ( SUModelRef  model, size_t  len, SUAttributeDictionaryRef  dictionaries[], size_t *  count  )

related

Retrieves the attribute dictionaries of a model object.

Parameters

[in]	model	The model object.
[in]	len	The number of attribute dictionaries to retrieve.
[out]	dictionaries	The dictionaries retrieved.
[out]	count	The number of attribute dictionaries retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if dictionaries or count is NULL

enum SUResult SUModelGetAttributeDictionary ( SUModelRef  model, const char *  name, SUAttributeDictionaryRef *  dictionary  )

related

Retrieves the attribute dictionary of a model object that has the given name. If a dictionary with the given name does not exist, one is added to the model object.

Parameters

[in]	model	The model object.
[in]	name	The name of the attribute dictionary to retrieve. Assumed to be UTF-8 encoded.
[out]	dictionary	The dictionary object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if name is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if dictionary is NULL

enum SUResult SUModelGetAxes ( SUModelRef  model, SUAxesRef *  axes  )

related

Retrieves the axes of a model object.

Parameters

[in]	model	The model object.
[out]	axes	The axes object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if axes is NULL

enum SUResult SUModelGetBehavior ( SUModelRef  model, struct SUComponentBehavior *  behavior  )

related

Retrieves the component behavior of a SketchUp model.

Since

SketchUp 2021.1, API 9.1

Parameters

[in]	model
[out]	behavior	The behavior retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if behavior is invalid

enum SUResult SUModelGetCamera ( SUModelRef  model, SUCameraRef *  camera  )

related

Retrieves the camera of a model object. The returned camera object points to model's internal camera. So it must not be released via SUCameraRelease().

Parameters

[in]	model	The model object.
[out]	camera	The camera object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if camera is NULL

enum SUResult SUModelGetClassifications ( SUModelRef  model, SUClassificationsRef *  classifications  )

related

Retrieves the classifications of a model object.

Parameters

[in]	model	The model object.
[out]	classifications	The classifications object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if classifications is NULL

enum SUResult SUModelGetComponentDefinitions ( SUModelRef  model, size_t  len, SUComponentDefinitionRef  definitions[], size_t *  count  )

related

Retrieves the component definitions that define component instances but not groups.

Parameters

[in]	model	The model object.
[in]	len	The number of component definitions to retrieve.
[out]	definitions	The component definitions retrieved.
[out]	count	The number of component definitions retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if definitions or count is NULL

enum SUResult SUModelGetDefaultLayer ( SUModelRef  model, SULayerRef *  layer  )

related

Retrieves the default layer object of a model object.

Parameters

[in]	model	The model object.
[out]	layer	The layer object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT of model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if layer is NULL

enum SUResult SUModelGetDescription ( SUModelRef  model, SUStringRef *  description  )

related

Retrieves the description of a model object.

Parameters

[in]	model	The model object.
[out]	description	The destination of the retrieved description object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if description is NULL
• SU_ERROR_INVALID_OUTPUT if description does not point to a valid SUStringRef object

enum SUResult SUModelGetDimensionStyle ( SUModelRef  model, SUDimensionStyleRef *  style  )

related

Retrieves the dimension style associated with a model object.

Since

SketchUp 2017, API 5.0

Parameters

[in]	model	The model object.
[out]	style	The dimension style retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if style is NULL

enum SUResult SUModelGetEntities ( SUModelRef  model, SUEntitiesRef *  entities  )

related

Retrieves the root model entities.

Parameters

[in]	model	The model object.
[out]	entities	The entities retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if entities is NULL

enum SUResult SUModelGetEntitiesByPersistentIDs ( SUModelRef  model, size_t  num_pids, const int64_t  pids[], SUEntityRef  entities[]  )

related

Retrieves entities by their persistent ids. The entities retrieved will be in the same order as to the peristent ids passed in. If a persistent id doesn't belong to a entity, then a SU_INVALID element will be returned along with SU_ERROR_PARTIAL_SUCCESS.

Since

SketchUp 2020.0, API 8.0

See Also

SUModelGetEntitiesOfTypeByPersistentIDs()

Deprecated:

Prefer the more flexible SUModelGetEntitiesOfTypeByPersistentIDs() which lets you narrow the search scope.

Parameters

[in]	model	The model object.
[in]	num_pids	The number of persistent ids.
[in]	pids	The persistent ids.
[out]	entities	The retrieved entity objects.

Returns

• SU_ERROR_NONE on success or if num_pids is zero
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_INPUT if pids is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if model is NULL
• SU_ERROR_PARTIAL_SUCCESS if one or more entities could not be found
• SU_ERROR_OVERWRITE_VALID if entities contains a valid SUEntityRef

enum SUResult SUModelGetEntitiesOfTypeByPersistentIDs ( SUModelRef  model, const uint32_t  type_flags, const size_t  num_pids, const int64_t  pids[], SUEntityRef  entities[]  )

related

Retrieves entities of a given type by their persistent ids. The entities retrieved will be in the same order as to the peristent ids passed in. If a persistent id doesn't belong to an entity, then a SU_INVALID element will be returned along with SU_ERROR_PARTIAL_SUCCESS.

Note

This method allows the user to search for specific types of entities which allows us to ignore parts of the model for faster results.

Since

SketchUp 2020.2, API 8.2

Parameters

[in]	model	The model object.
[in]	type_flags	An integer made up by combining Entity Type Flag values together with bitwise 'or'. This determines what types of entities to look for.
[in]	num_pids	The number of persistent ids.
[in]	pids	The persistent ids.
[out]	entities	The retrieved entity objects.

Returns

• SU_ERROR_NONE on success or if num_pids is zero
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_INPUT if pids is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if entities is NULL
• SU_ERROR_PARTIAL_SUCCESS if one or more entities could not be found
• SU_ERROR_OVERWRITE_VALID if entities contains a valid SUEntityRef

enum SUResult SUModelGetFonts ( SUModelRef  model, size_t  len, SUFontRef  fonts[], size_t *  count  )

related

Retrieves all the fonts associated with a model object.

Since

SketchUp 2017, API 5.0

Parameters

[in]	model	The model object.
[in]	len	The number of font objects to retrieve.
[out]	fonts	The font objects retrieved.
[out]	count	The number of font objects retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if fonts or count is NULL

enum SUResult SUModelGetGroupDefinitions ( SUModelRef  model, size_t  len, SUComponentDefinitionRef  definitions[], size_t *  count  )

related

Retrieves the component definitions that define groups.

Since

SketchUp 2016, API 4.0

Parameters

[in]	model	The model object.
[in]	len	The number of component definitions to retrieve.
[out]	definitions	The component definitions retrieved.
[out]	count	The number of component definitions retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if definitions or count is NULL

enum SUResult SUModelGetGuid ( SUModelRef  model, SUStringRef *  guid  )

related

Retrieves the guid of a model object.

Since

SketchUp 2019.2, API 7.1

See Also

SUComponentDefinitionGetGuid

SUSkpReadGuid

Parameters

[in]	model	The model object.
[out]	guid	The guid string.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if guid is NULL
• SU_ERROR_INVALID_OUTPUT if guid does not point to a valid SUStringRef object

enum SUResult SUModelGetImageDefinitions ( SUModelRef  model, size_t  len, SUComponentDefinitionRef  definitions[], size_t *  count  )

related

Retrieves the component definitions that define images.

Since

SketchUp 2019, API 7.0

Parameters

[in]	model	The model object.
[in]	len	The number of component definitions to retrieve.
[out]	definitions	The component definitions retrieved.
[out]	count	The number of component definitions retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if definitions or count is NULL

enum SUResult SUModelGetInstancePathByPid ( SUModelRef  model, SUStringRef  pid_ref, SUInstancePathRef *  instance_path_ref  )

related

Retrieves the instance path (including an entity) corresponding to a given persistent id.

Parameters

[in]	model	The model object.
[in]	pid_ref	Persistent id of the entity.
[out]	instance_path_ref	Instance path to the entity.

Note

Starting in SketchUp 2020.1, API 8.1, SU_ERROR_NO_DATA will be returned if pid_ref isn't a valid instance path in the model.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model or pid_ref are not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if instance_path_ref is NULL
• SU_ERROR_NO_DATA if the persistent id path didn't exist in the model
• SU_ERROR_INVALID_OUTPUT if instance_path_ref is not a valid object
• SU_ERROR_PARTIAL_SUCCESS if an instance path can not be is fully traced
• SU_ERROR_GENERIC on general failure

enum SUResult SUModelGetLayerFolders ( SUModelRef  model, size_t  len, SULayerFolderRef *  layer_folders, size_t *  count  )

related

Gets the SULayerFolderRef objects that are owned by the given model.

Since

SketchUp 2021.0, API 9.0

Parameters

[in]	model	The model object.
[in]	len	The number of elements in layer_folders.
[out]	layer_folders	An array of layer folder objects.
[out]	count	The number of elements written into layer_folders.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if layer_folders or count is NULL

enum SUResult SUModelGetLayers ( SUModelRef  model, size_t  len, SULayerRef  layers[], size_t *  count  )

related

Retrieves the layers in a model object.

Note

This retrieves all layers regardless of whether or not they are contained in a SULayerFolderRef.

Parameters

[in]	model	The model object.
[in]	len	The number of layers to retrieve.
[out]	layers	The layers retrieved.
[out]	count	The number of layers retrieved.

See Also

SUModelGetTopLevelLayers()

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT of model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if layers or count is NULL

enum SUResult SUModelGetLayersByPersistentIDs ( SUModelRef  model, size_t  num_pids, const int64_t  pids[], SULayerRef  layers[]  )

related

Retrieves layers by their persistent ids. The layers retrieved will be in the same order as to the peristent ids passed in. If a persistent id doesn't belong to a layer, then a SU_INVALID element will be returned along with SU_ERROR_PARTIAL_SUCCESS.

Since

SketchUp 2020.0, API 8.0

See Also

SUModelGetEntitiesOfTypeByPersistentIDs()

Deprecated:

Prefer the more flexible SUModelGetEntitiesOfTypeByPersistentIDs() which lets you narrow the search scope.

Parameters

[in]	model	The model object.
[in]	num_pids	The number of persistent ids.
[in]	pids	The persistent ids.
[out]	layers	The retrieved layer objects.

Returns

• SU_ERROR_NONE on success or if num_pids is zero
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_INPUT if pids is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if layer is NULL
• SU_ERROR_PARTIAL_SUCCESS if one or more layers could not be found
• SU_ERROR_OVERWRITE_VALID if layers contains a valid SULayerRef

enum SUResult SUModelGetLengthFormatter ( SUModelRef  model, SULengthFormatterRef *  formatter  )

related

Retrieves length formatter settings from the model. The given length formatter object must have been constructed using SULengthFormatterCreate(). It must be released using SULengthFormatterRelease().

Since

SketchUp 2018, API 6.0

Parameters

[in]	model	The model object.
[out]	formatter	The formatter used to retrieve the settings.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if formatter is NULL
• SU_ERROR_INVALID_OUTPUT if formatter does not point to a valid SULengthFormatterRef object

enum SUResult SUModelGetLineStyles ( SUModelRef  model, SULineStylesRef *  line_styles  )

related

Retrieves line styles from the model.

Since

SketchUp 2019, API 7.0

Parameters

[in]	model	The model object.
[out]	line_styles	The line styles of the model.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if line_styles is NULL

enum SUResult SUModelGetLocation ( SUModelRef  model, SULocationRef *  location  )

related

Retrieves the location information of a given model.

Parameters

[in]	model	The model object.
[out]	location	The location retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if location is NULL

enum SUResult SUModelGetMaterials ( SUModelRef  model, size_t  len, SUMaterialRef  materials[], size_t *  count  )

related

Retrieves all the materials associated with a model object.

Parameters

[in]	model	The model object.
[in]	len	The number of material objects to retrieve.
[out]	materials	The material objects retrieved.
[out]	count	The number of material objects retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if materials or count is NULL

enum SUResult SUModelGetName ( SUModelRef  model, SUStringRef *  name  )

related

Retrieves the name of a model object.

Parameters

[in]	model	The model object.
[out]	name	The destination of the retrieved name object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
• SU_ERROR_INVALID_OUTPUT if name does not point to a valid SUStringRef object

enum SUResult SUModelGetNorthCorrection ( SUModelRef  model, double *  north_correction  )

related

Retrieves the angle which will rotate the north direction to the y-axis for a given model.

Parameters

[in]	model	The model object.
[out]	north_correction	The north correction angle retrieved (in degrees).

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if north_angle is NULL

enum SUResult SUModelGetNumAllMaterials ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of all the materials in a model including those belonging to SUImageRef and SULayerRef.

Warning

Materials from SUImageRef and SULayerRef should not be applied to any other entity in the model. They are uniquely owned by the image or layer.

Since

SketchUp 2019.2, API 7.1

Parameters

[in]	model	The model object.
[out]	count	The number of material objects available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumAttributeDictionaries ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of attribute dictionaries of a model object.

Parameters

[in]	model	The model object.
[out]	count	The number of attribute dictionaries available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumComponentDefinitions ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of components associated with a model.

Parameters

[in]	model	The model object.
[out]	count	The number of components available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumFonts ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of fonts in a model object.

Since

SketchUp 2017, API 5.0

Parameters

[in]	model	The model object.
[out]	count	The number of font objects available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumGroupDefinitions ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of component definitions that define groups.

Since

SketchUp 2016, API 4.0

Parameters

[in]	model	The model object.
[out]	count	The number of component definitions available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumImageDefinitions ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of component definitions that define images.

Since

SketchUp 2019, API 7.0

Parameters

[in]	model	The model object.
[out]	count	The number of component definitions available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumLayerFolders ( SUModelRef  model, size_t *  count  )

related

Gets the number of SULayerFolderRef objects owned by the given model.

Since

SketchUp 2021.0, API 9.0

Parameters

[in]	model	The model object.
[out]	count	The number of layer folder objects.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumLayers ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of layers in a model object.

Note

This counts all layers regardless of whether or not they are contained in a SULayerFolderRef.

Parameters

[in]	model	The model object.
[out]	count	The number of layers available.

See Also

SUModelGetNumTopLevelLayers()

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT of model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumMaterials ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of materials in a model object.

Parameters

[in]	model	The model object.
[out]	count	The number of material objects available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetNumScenes ( SUModelRef  model, size_t *  num_scenes  )

related

Retrieves the number of scene cameras of a model object.

Parameters

[in]	model	The model object.
[out]	num_scenes	The number of scenes available.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if num_scenes is NULL

enum SUResult SUModelGetNumTopLevelLayers ( SUModelRef  model, size_t *  count  )

related

Retrieves the number of layers in a model object that have not been added to any layer folder.

Since

SketchUp 2021.0, API 9.0

Parameters

[in]	model	The model object.
[out]	count	The number of top-level layers available.

See Also

SUModelGetNumLayers()

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUModelGetOptionsManager ( SUModelRef  model, SUOptionsManagerRef *  options_manager  )

related

Retrieves options manager associated with the model.

Parameters

[in]	model	The model object.
[out]	options_manager	The options manager object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if options_manager is NULL

enum SUResult SUModelGetPath ( SUModelRef  model, SUStringRef *  path  )

related

Retrieves the file path of a model object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	model	The model object.
[out]	path	The destination of the retrieved path object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if path is NULL
• SU_ERROR_INVALID_OUTPUT if path does not point to a valid SUStringRef object

enum SUResult SUModelGetRenderingOptions ( SUModelRef  model, SURenderingOptionsRef *  rendering_options  )

related

Retrieves the rendering options of a model object.

Parameters

[in]	model	The model object.
[out]	rendering_options	The rendering options object retrieved. This object is owned by the model and must not be explicitly released.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if rendering_options is NULL
• SU_ERROR_NO_DATA if no rendering options is available

enum SUResult SUModelGetScenes ( SUModelRef  model, size_t  len, SUSceneRef  scenes[], size_t *  count  )

related

Retrieves all the scenes associated with a model object.

Parameters

[in]	model	The model object.
[in]	len	The number of scene objects to retrieve.
[out]	scenes	The scene objects retrieved.
[out]	count	The number of scene objects retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if scenes or count is NULL
• SU_ERROR_OVERWRITE_VALID if any element of scenes is already a valid object
• SU_ERROR_NO_DATA if there are no scene objects to retrieve.

enum SUResult SUModelGetSceneWithName ( SUModelRef  model, const char *  name, SUSceneRef *  scene  )

related

Retrieves the scenes with the given name associated with a model object.

Parameters

[in]	model	The model object.
[in]	name	The name of scene object to retrieve.
[out]	scene	The scene object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if name is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if scene is NULL
• SU_ERROR_NO_DATA if there are no scene objects to retrieve.

enum SUResult SUModelGetSelection ( SUModelRef  model, SUSelectionRef *  selection  )

related

Retrieves the selection object for a model.

Note

This method only works from within the SketchUp application.

Since

SketchUp 2020.2, API 8.2

Parameters

[in]	model	The model object.
[out]	selection	The retrieved selection object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if selection is NULL
• SU_ERROR_OVERWRITE_VALID if selection is already a valid object
• SU_ERROR_NO_DATA if this isn't called from within SketchUp

enum SUResult SUModelGetShadowInfo ( SUModelRef  model, SUShadowInfoRef *  shadow_info  )

related

Retrieves the shadow info of a model object.

Since

SketchUp 2015, API 3.0

Parameters

[in]	model	The model object.
[out]	shadow_info	The shadow info object retrieved. This object is owned by the model and must not be explicitly released.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if shadow_info is NULL
• SU_ERROR_NO_DATA if no shadow info is available

enum SUResult SUModelGetStatistics ( SUModelRef  model, struct SUModelStatistics *  statistics  )

related

Calculates the sum of all entities by type in the model.

Parameters

[in]	model	The model object.
[out]	statistics	The SUModelStatistics() struct that will be populated with the number of each entity type in the model.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if statistics is NULL

enum SUResult SUModelGetStyles ( SUModelRef  model, SUStylesRef *  styles  )

related

Retrieves the styles of a model object.

Since

SketchUp 2017, API 5.0

Parameters

[in]	model	The model object.
[out]	styles	The styles object retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if manager is NULL

enum SUResult SUModelGetTitle ( SUModelRef  model, SUStringRef *  title  )

related

Retrieves the title of a model object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	model	The model object.
[out]	title	The destination of the retrieved title object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if title is NULL
• SU_ERROR_INVALID_OUTPUT if title does not point to a valid SUStringRef object

enum SUResult SUModelGetTopLevelLayers ( SUModelRef  model, size_t  len, SULayerRef  layers[], size_t *  count  )

related

Retrieves the layers in a model that have not been added to a layer folder.

Since

SketchUp 2021.0, API 9.0

Parameters

[in]	model	The model object.
[in]	len	The number of layers to retrieve.
[out]	layers	The layers retrieved.
[out]	count	The number of layers retrieved.

See Also

SUModelGetLayers()

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if layers or count is NULL

enum SUResult SUModelGetUnits ( SUModelRef  model, enum SUModelUnits *  units  )

related

Returns the units associated with the given model.

Parameters

[in]	model	The model object.
[out]	units	The units retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_OUTPUT if the units argument is invalid

enum SUResult SUModelGetVersion ( SUModelRef  model, int *  major, int *  minor, int *  build  )

related

Retrieves the version of a model object. The version consists of three numbers: major version number, minor version number, and the build number.

Parameters

[in]	model	The model object.
[out]	major	The major version number retrieved.
[out]	minor	The minor version number retrieved.
[out]	build	The build version number retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if major, minor, or build is NULL

enum SUResult SUModelIsDrawingElementVisible ( SUModelRef  model, SUInstancePathRef  path, bool *  visible  )

related

Reports whether the given SUDrawingElementRef in an SUInstancePathRef is visible given the model's rendering options. This will take into account "DrawHiddenGeometry" and "DrawHiddenObjects" to determine if the drawing element is visible in the viewport.

Since

SketchUp 2020.0, API 8.0

Parameters

[in]	model	The model object.
[in]	path	The instance path to resolve visibility for.
[out]	visible	The retrieved layer objects.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_INVALID_INPUT if path is an invalid object
• SU_ERROR_INVALID_ARGUMENT if the instance path is not valid in the model
• SU_ERROR_NULL_POINTER_OUTPUT if visible is NULL

enum SUResult SUModelIsGeoReferenced ( SUModelRef  model, bool *  is_geo_ref  )

related

Retrieves whether the model is georeferenced.

Since

SketchUp 2017, API 5.0

Parameters

[in]	model	The model object.
[out]	is_geo_ref	The flag retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if is_used is NULL

enum SUResult SUModelLoadDefinition ( SUModelRef  model, const char *  filename, SUComponentDefinitionRef *  definition  )

related

Loads a component from a file.

Deprecated:

This method will be removed in SketchUp 2022.0. It is replaced by SUModelLoadDefinitionWithStatus() which can load components saved by newer versions of SketchUp.

Since

SketchUp 2019.2, API 7.1

Parameters

[in]	model	The model object.
[in]	filename	The full path and filename to a SkethchUp model.
[out]	definition	The component definition that is created after load.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if filename is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if definition is NULL
• SU_ERROR_OVERWRITE_VALID if definition is already a valid object
• SU_ERROR_SERIALIZATION if loading the file failed

enum SUResult SUModelLoadDefinitionWithStatus ( SUModelRef  model, const char *  filename, SUComponentDefinitionRef *  definition, enum SUModelLoadStatus *  status  )

related

Loads a component from a file.

Since

SketchUp 2021, API 9.0

Note

As of SketchUp 2021.0, SketchUp can open .skp files created with newer versions of SketchUp. However, opening newer versions with an older SDK might omit model data. Use the load status value to check if the file was created with a newer version of SketchUp.

Warning

When reading a file created with a newer version of SketchUp, you may lose data if you write over the same file.

Parameters

[in]	model	The model object.
[in]	filename	The full path and filename to a SkethchUp model.
[out]	definition	The component definition that is created after load.
[out]	status	Returns additional information on the status of a successful operation. Valid when the return value is SU_ERROR_NONE.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if filename is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if definition is NULL
• SU_ERROR_NULL_POINTER_OUTPUT if status is NULL
• SU_ERROR_OVERWRITE_VALID if definition is already a valid object
• SU_ERROR_MODEL_VERSION if the component file has a newer version than is supported by the current build of the SDK.
• SU_ERROR_SERIALIZATION if loading the file failed

enum SUResult SUModelMergeCoplanarFaces ( SUModelRef  model )

related

Merges all adjacent, coplanar faces in the model.

Parameters

[in]

model

The model object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid

enum SUResult SUModelOrientFacesConsistently ( SUModelRef  model, bool  recurse_components  )

related

Updates the faces in the model so that they are oriented consistently.

Since

SketchUp 2018, API 6.0

Parameters

[in]	model	The model object.
[in]	recurse_components	Orient components of the model.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object

enum SUResult SUModelPurgeEmptyLayerFolders ( SUModelRef  model, size_t *  count  )

related

Removes empty SULayerFolderRef objects from the model.

Since

SketchUp 2021.0, API 9.0

Parameters

[in]	model	The model object.
[out]	count	The number of empty layer folders removed. If NULL, count will not be retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object

enum SUResult SUModelPurgeUnusedLayers ( SUModelRef  model, size_t *  count  )

related

Removes unused SULayerRef objects from the model.

Since

SketchUp 2020.2, API 8.2

Parameters

[in]	model	The model object.
[out]	count	The number of layers deleted. If NULL, count will not be retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object

enum SUResult SUModelRelease ( SUModelRef *  model )

related

Releases a model object and its associated resources. The root component of the model object and all its child objects must not be released explicitly.

Parameters

[in]

model

The model object.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_INPUT if model is NULL

enum SUResult SUModelRemoveComponentDefinitions ( SUModelRef  model, size_t  len, SUComponentDefinitionRef  components[]  )

related

Remove definitions of components, images, and groups from a model object. All component definitions, their geometry, and attached instances will be released.

Since

SketchUp 2019.2, API 7.1

Parameters

[in]	model	The model object.
[in]	len	The number of component definitions to remove.
[in]	components	The array of component definitions to remove.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_OUT_OF_RANGE if the number of components is less than one
• SU_ERROR_NULL_POINTER_INPUT if components is NULL
• SU_ERROR_PARTIAL_SUCCESS if removing a component definition fails mid-process

enum SUResult SUModelRemoveLayerFolders ( SUModelRef  model, size_t  len, SULayerFolderRef  layer_folders[]  )

related

Removes all layer folders provided in the array. All children of the deleted layer folders will be moved to the parent of the deleted folder.

Since

SketchUp 2021.0, API 9.0

Parameters

[in]	model	The model object.
[in]	len	The length of the array.
[in]	layer_folders	The layer folders to be deleted.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object.
• SU_ERROR_NULL_POINTER_INPUT if layer_folders is NULL
• SU_ERROR_OUT_OF_RANGE if len is less than one.
• SU_ERROR_INVALID_ARGUMENT if the number of successfully removed items in layer_folders is 0.
• SU_ERROR_PARTIAL_SUCCESS if we successfully remove at least 1 of the items provided in layer_folders but fail to remove others.

enum SUResult SUModelRemoveLayers ( SUModelRef  model, size_t  len, SULayerRef  layers[]  )

related

Removes all layers provided in the array. The default layer cannot be removed. All entities on the deleted layers will be moved to the default layer.

Since

SketchUp 2019.2 API 7.1

Parameters

[in]	model	The model object.
[in]	len	The length of the array.
[in]	layers	The layers to be deleted.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if layers is NULL
• SU_ERROR_OUT_OF_RANGE if len is less than one.
• SU_ERROR_PARTIAL_SUCCESS if removing the layers failed mid-process

enum SUResult SUModelRemoveMaterials ( SUModelRef  model, size_t  len, SUMaterialRef  materials[]  )

related

Removes all materials provided in the array.

Since

SketchUp 2019.2, API 7.1

Parameters

[in]	model	The model object.
[in]	len	The length of the array.
[in]	materials	The materials to be deleted.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if materials is NULL
• SU_ERROR_OUT_OF_RANGE if len is zero
• SU_ERROR_PARTIAL_SUCCESS if removing the materials failed mid-process
• SU_ERROR_NO_DATA if materials provided are invalid

enum SUResult SUModelRemoveScenes ( SUModelRef  model, size_t  len, SUSceneRef  scenes[]  )

related

Removes selected scenes from a model.

Since

SketchUp 2019.2, API 7.1

Parameters

[in]	model	The model object.
[in]	len	The number of scenes in the array for removal.
[in]	scenes	The scenes to be deleted from the model.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_OUT_OF_RANGE if len is zero
• SU_ERROR_PARTIAL_SUCCESS if the deletion process failed mid-process or if not all of scenes for deletion were found in the model
• SU_ERROR_NO_DATA if none of the requested scenes could be found for deletion

enum SUResult SUModelSaveToFile ( SUModelRef  model, const char *  file_path  )

related

Saves the model to a file.

Note

Prior to SketchUp 2019.2, API 7.1 this function did not generate a new model GUID.

Parameters

[in]	model	The model object.
[in]	file_path	The file path destination of the serialization operation. Assumed to be UTF-8 encoded.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
• SU_ERROR_SERIALIZATION if the serialization operation itself fails

enum SUResult SUModelSaveToFileWithVersion ( SUModelRef  model, const char *  file_path, enum SUModelVersion  version  )

related

Saves the model to a file using a specific SketchUp version format.

Note

Prior to SketchUp 2019.2, API 7.1 this function did not generate a new model GUID.

Since

SketchUp 2014, API 2.0

Parameters

[in]	model	The model object.
[in]	file_path	The file path destination of the serialization operation. Assumed to be UTF-8 encoded.
[in]	version	The SKP file format version to use when saving.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_MODEL_VERSION if version is invalid
• SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
• SU_ERROR_SERIALIZATION if the serialization operation itself fails

enum SUResult SUModelSetActiveLayer ( SUModelRef  model, SULayerRef  layer  )

related

Sets the active layer object of a model object.

Since

SketchUp 2020, API 8.0

Parameters

[in]	model	The model object.
[in]	layer	The layer object to be set as the active layer.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_ARGUMENT if layer doesn't belong to model
• SU_ERROR_INVALID_INPUT if model or layer is not a valid object

enum SUResult SUModelSetActiveScene ( SUModelRef  model, SUSceneRef  scene  )

related

Sets the provided scene as the active scene.

Since

SketchUp 2016, API 4.0

Parameters

[in]	model	The model object.
[in]	scene	The scene object to be set as the active scene.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model or scene is not a valid object
• SU_ERROR_GENERIC if try to activate a scene which is not in the model

enum SUResult SUModelSetBehavior ( SUModelRef  model, const struct SUComponentBehavior *  behavior  )

related

Sets the component behavior of a SketchUp model.

Since

SketchUp 2021.1, API 9.1

Parameters

[in]	model
[in]	behavior	The behavior to set.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is invalid
• SU_ERROR_NULL_POINTER_INPUT if behavior is NULL

enum SUResult SUModelSetCamera ( SUModelRef  model, SUCameraRef *  camera  )

related

Sets the current camera of a model object.

Since

SketchUp 2016, API 4.0

Parameters

[in]	model	The model object.
[in]	camera	The camera object. This reference will become invalid when this function returns.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object
• SU_ERROR_INVALID_INPUT if camera is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if camera is NULL

enum SUResult SUModelSetDescription ( SUModelRef  model, const char *  description  )

related

Sets the description of a model object.

Parameters

[in]	model	The model object.
[in]	description	The description of the model object. Assumed to be UTF-8 encoded.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_INPUT if description is NULL

enum SUResult SUModelSetGeoReference ( SUModelRef  model, double  latitude, double  longitude, double  altitude, bool  is_z_value_centered, bool  is_on_ocean_floor  )

related

Georeferences the model.

Parameters

[in]	model	The model object.
[in]	latitude	Latitude of the model.
[in]	longitude	Longitude of the model.
[in]	altitude	Altitude of the model.
[in]	is_z_value_centered	Indicates if z value should be centered.
[in]	is_on_ocean_floor	Indicates whether the model is on the ocean floor.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is not a valid object or if latitude or longitude does not lie within a valid range

enum SUResult SUModelSetName ( SUModelRef  model, const char *  name  )

related

Sets the name of a model object.

Parameters

[in]	model	The model object.
[in]	name	The name of the model object. Assumed to be UTF-8 encoded.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if model is an invalid object
• SU_ERROR_NULL_POINTER_INPUT if name is NULL

---

The documentation for this struct was generated from the following files:

• SketchUpAPI/model/defs.h
• SketchUpAPI/model/model.h