SketchUp C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Related Functions
SUModelRef Struct Reference

A SketchUp model. More...

`#include <SketchUpAPI/model/model.h>`

## Related Functions
(Note that these are not member functions.)
enum SUResult | SUModelCreateOverlay (SUModelRef model, const struct SUOverlayCreateInfo *info, SUOverlayRef *overlay)
| Creates an overlay and adds it to the model. More...
enum SUResult | SUModelReleaseOverlay (SUModelRef model, SUOverlayRef *overlay)
| Releases the overlay after removing it from the model. More...
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 | SUModelGetEnvironments (SUModelRef model, SUEnvironmentsRef *environments)
| Retrieves the environments collection in the model. 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 | SUModelLoadMaterial (SUModelRef model, const char *file_path, SUMaterialRef *material)
| Loads a material from a SKM file. 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 | SUModelReorderScene (SUModelRef model, SUSceneRef scene, size_t new_index)
| Reorder `scene` based on `new_index` to `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...
enum SUResult | SUModelGetNumActiveSectionPlanes (SUModelRef model, size_t *count)
| Retrieves the number of active section planes in the model. More...
enum SUResult | SUModelGetActiveSectionPlanes (SUModelRef model, size_t len, SUSectionPlaneRef active_section_planes[], size_t *count)
| Retrieves the active section planes in the 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,out] | 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,out] | 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,out] | 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,out] | 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,out] | 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,out] | 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.

Note
  When adding a scene the current state of the model is saved to the scene based on the SUSceneFlags set on the scene prior to adding it.

Parameters

  [in,out] | 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 SUModelCreateOverlay | ( | SUModelRef | model,
|  | const struct SUOverlayCreateInfo * | info,
|  | SUOverlayRef * | overlay
| ) |  |
| related

Creates an overlay and adds it to the model.

Since
  SketchUp 2024, API 12.0

Parameters

  [in] | model | The model object
  [in] | info | The information needed to create the overlay object
  [out] | overlay | The created overlay object

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `model` is an invalid object
  - SU_ERROR_NULL_POINTER_INPUT if `info` is NULL
  - SU_ERROR_NULL_POINTER_OUTPUT if `overlay` is NULL
  - SU_ERROR_OVERWRITE_VALID if `overlay` is already a valid object
  - SU_ERROR_DUPLICATE if the given SUOverlayCreateInfo::id already exists in the model

See Also
  SUOverlayRef

enum SUResult SUModelFixErrors | ( | SUModelRef | model | ) |
| related

Fixes any errors found in the given model.

Since
  SketchUp 2018, API 6.0

Parameters

  [in,out] | 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 SUModelGetActiveSectionPlanes | ( | SUModelRef | model,
|  | size_t | len,
|  | SUSectionPlaneRef | active_section_planes[],
|  | size_t * | count
| ) |  |
| related

Retrieves the active section planes in the model.

Since
  SketchUp 2025.1, API 13.1

Parameters

  [in] | model | The model object.
  [in] | len | The number of active section planes to retrieve.
  [out] | active_section_planes | The active section planes retrieved.
  [out] | count | The number of active section planes retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `model` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `active_section_planes` or `count` is `NULL`

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 | The model object.
  [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 SUModelGetEnvironments | ( | SUModelRef | model,
|  | SUEnvironmentsRef * | environments
| ) |  |
| related

Retrieves the environments collection in the model.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | model | The model object.
  [out] | environments | The environments collection retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if model is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if environments is NULL

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

Retrieves all the fonts associated with a model object.

Note
  The returned font references may become invalid if another font is assigned to objects using them later.

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 SUModelGetNumActiveSectionPlanes | ( | SUModelRef | model,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of active section planes in the model.

Since
  SketchUp 2025.1, API 13.1

Parameters

  [in] | model | The model object.
  [out] | count | The number of active section planes.

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 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.

Note
  See SUEntityType for examples on how it is defined depending on whether the code is compiled as C or C++. (Related to a bug in the original implementation).

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

See Also
  SUEntityType
  SUModelStatistics
  SUModelGetStatistics

// Usage from a C compiler:
SUModelStatistics statistics;
SUModelGetStatistics(model, &statistics);
std::cout << "Faces: " << statistics.entity_counts[SUEntityType_Face] << "\n";
// Usage from a C++ compiler:
SUModelStatistics statistics;
SUModelGetStatistics(model, &statistics);
std::cout << "Faces: " << statistics.entity_counts[SUModelStatistics::SUEntityType_Face] << "\n";

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,out] | 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,out] | 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 SUModelLoadMaterial | ( | SUModelRef | model,
|  | const char * | file_path,
|  | SUMaterialRef * | material
| ) |  |
| related

Loads a material from a SKM file.

If a matching material exists in the model it will be returned instead.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in,out] | model | The model object.
  [in] | file_path | The location to load the material from. Assumed to be UTF-8 encoded.
  [out] | material | The material object.

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_OVERWRITE_VALID if `material` is already a valid object
  - SU_ERROR_SERIALIZATION if the serialization operation itself fails

enum SUResult SUModelMergeCoplanarFaces | ( | SUModelRef | model | ) |
| related

Merges all adjacent, coplanar faces in the model.

Parameters

  [in,out] | 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,out] | 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,out] | 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,out] | 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,out] | 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 SUModelReleaseOverlay | ( | SUModelRef | model,
|  | SUOverlayRef * | overlay
| ) |  |
| related

Releases the overlay after removing it from the model.

Parameters

  [in] | model | The model object
  [in,out] | overlay | The overlay object to be released, will be set to NULL on return.

Since
  SketchUp 2024, API 12.0

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `model` or `overlay` is an invalid object
  - SU_ERROR_NULL_POINTER_INPUT if `overlay` is NULL
  - SU_ERROR_NO_DATA if `overlay` could be found in the model

See Also
  SUOverlayRef

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,out] | 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,out] | 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,out] | 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,out] | 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,out] | 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 SUModelReorderScene | ( | SUModelRef | model,
|  | SUSceneRef | scene,
|  | size_t | new_index
| ) |  |
| related

Reorder `scene` based on `new_index` to `model` object.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in,out] | model | The `model` object.
  [in] | scene | The `scene` object to reorder.
  [in] | new_index | The `new_index` where the scene should be placed.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `model` or `scene` are not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `scene` does not exists within `model`
  - SU_ERROR_OUT_OF_RANGE if the `new_index` is greater than the number of scenes in the model

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,out] | 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,out] | 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,out] | model | The model object.
  [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,out] | model | The model object.
  [in,out] | 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,out] | 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,out] | 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,out] | 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/application/model.h
- SketchUpAPI/model/model.h