File Solid
Solid element with properties derived from external file
Description
The File Solid block models a solid element with
geometry, inertia, color, and reference frame derived from an external file. The file
must be of a part model, which is to say that it contains at least solid geometry data.
Some formats may provide color and inertia data, though such properties can be specified
manually if need be.
Among the supported formats are those native to CATIA (V4, V5, and V6), Creo,
Inventor, Unigraphics NX, Solid Edge, SolidWorks, and Parasolid (all CAD applications
common in industry and academia). These include CATPART, PRT, IPT, SLDPRT, and X_T (and
its binary version, X_B). Other valid formats, not associated with a specific
application but common in 3-D modeling, include SAT (often referred to as ACIS), JT,
STL, and STEP.
(CAD drawing and assembly files, which do not contain the necessary data for a solid
element, cannot be imported to the block.)
Inertia Calculations
For part model files with density data, the block gives the option to
(automatically) set the mass, center of mass, and inertia tensor of the solid from
calculation. This behavior is enabled by default (through the
Type and Based On parameters under the
Inertia node, which, in their original states, will read
Calculate from Geometry
and Density from
File
).
If the imported file does not contain density data, you must specify it (or,
equivalently, mass) for the calculations to be made. Set the Based
On parameter to Custom Density
or
Custom Mass
to enter the missing data.
Alternatively, if you have the complete mass properties of the imported part—often
provided, for CAD models, by the CAD application itself—you can enter them directly
as block parameters. Set the inertia Type parameter to
Custom
in order to do this.
Note that the frame in which the moments and products of inertia are defined will
vary among CAD applications. In this block, the origin of that frame is assumed to
be at the center of mass (and its axes parallel to those of the reference frame).
This frame is referred to here as the inertia resolution frame. (The center of mass,
on the other hand, is defined in the reference frame.) For more information, see
Specifying Custom Inertias.
Derived Values
If the mass properties are computed from geometry, you can view their values
in the block dialog box. To do so, expand the Derived
Values node under Inertia and click
Update. (This feature, as it is specified to computed
properties, requires that the inertia Type setting be
Calculated from Geometry
.) If a geometry or
inertia block parameter changes, click the Update button
once again to display the new mass properties. All values are in SI units of
length (m
) and mass (kg
).
Solid Visualization
The block dialog box contains a collapsible visualization pane. This pane provides
instant visual feedback on the solid you are modeling. Use it to find and fix any
issues with the shape and color of the solid. You can examine the solid from
different perspectives by selecting a standard view or by rotating, panning, and
zooming the solid.
Select the Update Visualization button
to view the latest changes to the solid geometry
in the visualization pane. Select Apply or
OK to commit your changes to the solid. Closing the block
dialog box without first selecting Apply or
OK causes the block to discard those changes.
Right-click the visualization pane to access the visualization context-sensitive
menu. This menu provides additional options so that you can change the background
color, split the visualization pane into multiple tiles, and modify the view
convention from the default +Z up (XY Top) setting.
Connection Frames
Like most components, the solid connects through frames, of which it has at least
one. The default frame, which serves as its reference and is associated with port
R, gets its origin and axes from the data in the imported
file. (The origin is generally the zero coordinate of the CAD model or, if such
technology is used, the 3-D scan, contained in the file.)
For those cases in which the reference frame is ill-placed for connection, or in
which multiple connection frames are needed, the block comes with a frame creation
tool. Treat this tool as an interactive alternative to the Rigid
Transform block (the latter a numerical means to add and
translate as well as rotate frames, though one that keeps the frames separate from
the solid).
You can create (and edit) frames using geometry features as constraints—placing
the frame origin on, and orienting the frame axes along, selected vertices, edges,
and faces. You can also use the reference frame origin and its axes, as well as the
center of mass and the principal inertia axes, to define the new frames. Each frame
adds to the block a new frame port (its label derived from the name given in the
frame creation pane).
To create or edit a frame, first expand the Frames node in
the block dialog box. Click the
button to create a frame or the
button to edit a frame (if one, other than the
reference frame, already exists). The frame definitions depend on a mix of geometry
and inertia data, so you must have previously imported a part geometry file. If a
block parameter changes, you must refresh the visualization pane (by clicking the
button) in order to create or edit a
frame.
Frame Definition
A custom frame is fully defined when its origin and axes are too. Of these,
the axes require the most care. You must specify two axes, one primary and one
secondary. The primary axis defines the plane (that normal to it) on which the
other axes must lie. The secondary axis is merely the projection of a selected
direction—axis or geometry feature—on that plane.
The remaining (and unspecified) axis is set by requiring that all three be
perpendicular and ordered according to the right-hand rule. Naturally, the
secondary axis must have a vector component perpendicular to the primary axis.
If the two are parallel, the frame is invalid. If the frame is then saved, its
orientation is set to that of the reference frame.
To use a geometry feature for the frame origin or axis definitions:
In the frame creation pane, select the Based on
Geometric Feature radio button.
In the solid visualization pane, click a vertex, edge, or face.
Zoom in, if necessary, to more precisely select a feature.
Again in the frame creation pane, click the Use Selected
Feature button.
MATLAB Variables
It is common in a model to parameterize blocks in terms of MATLAB variables.
Instead of a scalar, vector, or string, for example, a block parameter will have in
its field the name of a variable. The variable is defined elsewhere, often in a
subsystem mask or in the model workspace, sometimes by reference to an external M
file.
This approach suits complex models in which multiple blocks must share the same
parameter value—a common density, say, or color, if defined as an RGB vector. When
the MATLAB variable definition then changes, so do all block parameters that depend
on it. Consider using MATLAB variables here if a parameter is likely to be shared by
several blocks in a large model.
(For a simple example with solid blocks parameterized in terms of workspace
variables, open the sm_compound_body
model)
Exporting Geometry Properties
The File Solid block can generate a convex hull geometry
representation of an imported CAD file in the Simscape Multibody environment. This
geometric data can be used to model spatial contact forces.
As shown in the figure, the convex hull geometry is an approximation of the true
geometry. Note that the block calculates the physical properties, such as mass and
inertia, based on its true geometry.
Ports
Frame
expand all
R
— Reference frame
frame
Frame by which to connect the solid in a model. The frame node to
which this port connects—generally another frame port or a frame
junction—determines the position and orientation of the solid relative
to other components. Add a Rigid
Transform block between the port and the node if the
frames they represent must be offset from one another.
Parameters
expand all
Geometry
File Name
— Name of the part model file to import
custom character vector
Name and extension of the part model file to import. If the file is not on
the MATLAB path, the file location must be specified. The file location can
be specified as an absolute path, starting from the root directory of the
file system—e.g., 'C:/Users/JDoe/Documents/myShape.STEP'
.
It can also be specified as a relative path, starting from a folder on the
MATLAB path—e.g., 'Documents/myShape.STEP'
.
Unit Type
— Source for solid geometry units
From File
(default) | Custom
Source of the solid geometry units. Select From
File
to use the units specified in the imported file.
Select Custom
to specify your own units.
Unit
— Length units in which geometry coordinates are specified in the imported file
m
(default) | cm
| mm
| km
| in
| ft
Length units in which to interpret the geometry defined in a geometry
file. Changing the units changes the scale of the imported geometry.
Convex Hull
— Generate a convex hull representation of the true geometry
cleared
(default) | checked
Select to generate a convex hull
representation of the true geometry. This convex hull can be used to model
contacts between a pair of bodies by connecting the Spatial
Contact Force block.
Dependencies
To enable this option, select
under the .
Inertia
Type
— Inertia parameterization to use
Calculate from Geometry
(default) | Point Mass
| Custom
Inertia parameterization to use. Select Point
Mass
to model a concentrated mass with negligible
rotational inertia. Select Custom
to model a
distributed mass with the specified moments and products of inertia. The
default setting, Calculate from Geometry
, enables
the block to automatically calculate the rotational inertia properties from
the solid geometry and either density or mass.
Based on
— Parameter to base inertia calculation on
Density from File
(default) | Custom Density
| Custom Mass
Parameter to use in inertia calculation. The block calculates the inertia
tensor from the solid geometry and the parameter selected.
Use the default setting of Density from File
to
base the calculations on the density obtained from the imported file. (Note
that only some formats can carry density data. Of those that do, only some
will actually carry it. Often this data is specified in a CAD application
before saving or exporting the part model file.)
Use Custom Density
to specify a density other
than that obtained from the imported file. Use Custom
Mass
to instead specify the total mass of the
solid.
Density
— Mass per unit volume of material
1000 kg/m^3
(default)
Mass per unit volume of material. The mass density can take on a positive
or negative value. Specify a negative mass density to model the effects of a
void or cavity in a solid body.
Mass
— Total mass of the solid element
1 kg
(default) | scalar with units of mass
Total mass to attribute to the solid element. This parameter can be positive or
negative. Use a negative value to capture the effect of a void or cavity in a compound
body (one comprising multiple solids and inertias), being careful to ensure that the
mass of the body is on the whole positive.
Custom: Center of Mass
— Center-of-mass coordinates
[0 0 0] m
(default) | three-element vector with units of length
[x y z] coordinates of the center of mass relative to the block
reference frame. The center of mass coincides with the center of gravity
in uniform gravitational fields only.
Custom: Moments of Inertia
— Diagonal elements of inertia tensor
[1 1 1] kg*m^2
(default) | three-element vector with units of mass*length^2
Three-element vector with the [Ixx Iyy
Izz] moments of inertia specified relative to a frame with
origin at the center of mass and axes parallel to the block reference frame. The moments
of inertia are the diagonal elements of the inertia tensor
where:
Custom: Products of Inertia
— Off-diagonal elements of inertia tensor
[0 0 0] kg*m^2
(default) | three-element vector with units of mass*length^2
Three-element vector with the [Iyz Izx Ixy]
products of inertia specified relative to a frame with origin at the
center of mass and axes parallel to the block reference frame. The
products of inertia are the off-diagonal elements of the inertia tensor
where:
Derived Values
— Display of calculated values of mass properties
button
Display of the calculated values of the solid mass properties—mass, center
of mass, moments of inertia, and products of inertia. Click the
Update button to calculate and display the mass
properties of the solid. Click this button following any changes to the
block parameters to ensure that the displayed values are still
current.
The center of mass is resolved in the local reference frame of the solid.
The moments and products of inertia are each resolved in the inertia frame
of resolution—a frame whose axes are parallel to those of the reference
frame but whose origin coincides with the solid center of mass.
Dependencies
The option to calculate and display the mass properties is active when
the > block parameter is set to Calculate from
Geometry
.
Graphic
Type
— Graphic to use in the visualization of the solid
From Geometry
(default) | Marker
| None
Choice of graphic to use in the visualization of the solid. The graphic is
by default the geometry specified for the solid. Select
Marker
to show instead a simple graphic
marker, such as a sphere or cube. Change this parameter to
None
to eliminate this solid altogether from
the model visualization.
Marker: Shape
— Shape of the marker to assign to the solid
Sphere
(default) | Cube
| Frame
Shape of the marker by means of which to visualize the solid. The motion
of the marker reflects the motion of the solid itself.
Marker: Size
— Width of the marker in pixels
10
(default) | scalar with units of pixels
Width of the marker in pixels. This width does not scale with zoom level.
Note that the apparent size of the marker depends partly on screen
resolution, with higher resolutions packing more pixels per unit length, and
therefore producing smaller icons.
Visual Properties
— Parameterizations for color and opacity
Simple
(default) | Advanced
| From File
Parameterization for specifying visual properties. Select
Simple
to specify color and opacity. Select
Advanced
to add specular highlights, ambient
shadows, and self-illumination effects. Select From
File
if the imported file has color data and you want to
use it in the model.
(Only some file formats allow color data. In those that do, that data is
often optional. If your file does not specify color, the solid will take on
a gray hue (the default solid color). Select another parameterization to
customize color in such cases.)
Color
— True color as [R,G,B] vector on 0–1 scale
[0.5 0.5 0.5]
(default) | three-element vector with values constrained to 0–1
RGB color vector with red (R), green (G), and blue (B) color amounts specified on a
0–1 scale. A color picker provides an alternative interactive means of specifying a
color. If you change the Visual Properties setting to
Advanced
, the color specified in this parameter becomes
the Diffuse Color vector.
Dependencies
To enable this parameter, set :
Type to Marker
.
Visual Properties to
Simple
.
Opacity
— Surface opacity as scalar number on 0–1 scale
1.0
(default) | scalar with value constrained to 0–1
Graphic opacity specified on a scale of 0–1. An opacity of 0
corresponds to a completely transparent graphic and an opacity of 1
to a completely opaque graphic.
Dependencies
To enable this parameter, set :
Type to Marker
.
Visual Properties to
Simple
.
Diffuse Color
— True color as [R,G,B,A] vector on 0–1 scale
[0.5 0.5 0.5]
(default) | three- or four-element vector with values constrained to 0–1
True color under direct white light specified as an [R,G,B] or [R,G,B,A] vector on a
0–1 scale. An optional fourth element specifies the color opacity also on a scale of
0–1. Omitting the opacity element is equivalent to specifying a value of
1
.
Dependencies
To enable this parameter, set :
Type to Marker
.
Visual Properties to
Advanced
.
Specular Color
— Highlight color as [R,G,B,A] vector on 0–1 scale
[0.5 0.5 0.5 1.0]
(default) | three- or four-element vector with values constrained to 0–1
Color of specular highlights specified as an [R,G,B] or [R,G,B,A] vector on a 0–1
scale. The optional fourth element specifies the color opacity. Omitting the opacity
element is equivalent to specifying a value of 1
.
Dependencies
To enable this parameter, set :
Type to Marker
.
Visual Properties to
Advanced
.
Ambient Color
— Shadow color as [R,G,B,A] vector on 0–1 scale
[0.15 0.15 0.15 1.0]
(default) | three- or four-element vector with values constrained to 0–1
Color of shadow areas in diffuse ambient light, specified as an [R,G,B] or [R,G,B,A]
vector on a 0–1 scale. The optional fourth element specifies the color opacity. Omitting
the opacity element is equivalent to specifying a value of 1
.
Dependencies
To enable this parameter, set :
Type to Marker
.
Visual Properties to
Advanced
.
Emissive Color
— Self-illumination color as [R,G,B,A] vector on 0–1 scale
[0.0 0.0 0.0 1.0]
(default) | three- or four-element vector with values constrained to 0–1
Surface color due to self illumination, specified as an [R,G,B] or [R,G,B,A] vector on
a 0–1 scale. The optional fourth element specifies the color opacity. Omitting the
opacity element is equivalent to specifying a value of 1
.
Dependencies
To enable this parameter, set :
Type to Marker
.
Visual Properties to
Advanced
.
Shininess
— Highlight sharpness as scalar number on 0–128 scale
75
(default) | scalar with value constrained to 0–128
Sharpness of specular light reflections, specified as a scalar number on a 0–128
scale. Increase the shininess value for smaller but sharper highlights. Decrease the
value for larger but smoother highlights.
Dependencies
To enable this parameter, set :
Type to Marker
.
Visual Properties to
Advanced
.
Frames
Show Port R
— Show the reference frame port for connection to other blocks
checked (default) | cleared
Clear the check box to hide the reference frame port in the Solid block.
Hiding the reference frame port suppresses the frame visualization in
Mechanics Explorer. You must expose the reference frame port if the block
has no custom frames.
New Frame
— Create a custom frame for connection to other blocks
empty (default)
Frame Creation Interface
Frame Name
— MATLAB® string used to identify the custom frame
custom character vector
Frame identifier specified as a MATLAB string. This string identifies the frame port in the block
diagram and in the tree view pane of Mechanics Explorer. Keep the frame name
short to ensure it fits in the block icon width.
Frame Origin
— Position of the custom frame origin
At Reference Frame Origin (default) | At Center of Mass | Based on Geometric Feature
Select the location of the frame origin. Options include:
At Reference Frame Origin — Make
the new frame origin coincident with the reference frame origin.
This is the default option.
At Center of Mass — Make the new
frame origin coincident with the solid center of mass. The
reference frame origin is located at the center of mass in
symmetrical shapes such as spheres and bricks but not in certain
extrusions or revolutions.
Based on Geometric Feature — Place
the new frame origin at the center of the selected geometry
feature. Valid geometry features include surfaces, lines, and
points. You must select a geometry feature from the
visualization pane and then select the Use Selected
Feature button. The name of the selected geometry
feature appears in the field below this option.
Frame Axes: Primary Axis
— Axis used to constrain the possible directions of the remaining frame axes
Along Reference Frame Axis (default) | Along Principal Inertia Axis | Based on Geometric Feature
Select the axis of the new frame that you want to set as the primary axis.
The primary axis constrains the possible orientations of the remaining two
axes. Specify the orientation of the primary axis by selecting from the
following options:
Along Reference Frame Axis — Align
the primary axis with the selected axis of the reference
frame.
Along Principal Inertia Axis —
Align the primary axis with the selected principal inertia axis.
The principal inertia axes are those about which the products of
inertia are zero.
Based on Geometric Feature — Align
the primary axis with the vector associated with the selected
geometric feature. Valid geometric features include surfaces and
lines.
Frame Axes: Secondary Axis
— Axis used to constrain the possible directions of the remaining frame axis
Along Reference Frame Axis (default) | Along Principal Inertia Axis | Based on Geometric Feature
Select the axis of the new frame that you want to set as the secondary
axis. The secondary axis is the projection of the selected direction onto
the normal plane of the primary axis. Select the direction to project from
the following options:
Along Reference Frame Axis —
Project the selected reference frame axis onto the normal plane
of the primary axis. Align the secondary axis with the
projection.
Along Principal Inertia Axis —
Project the selected principal inertia axis onto the normal
plane of the primary axis. Align the secondary axis with the
projection. The principal inertia axes are those about which the
products of inertia are zero.
Based on Geometric Feature —
Project the vector associated with the selected geometry feature
onto the normal plane of the primary axis. Align the secondary
axis with the projection. Valid geometry features include
surfaces and lines. You must select a geometry feature from the
visualization pane and then select the Use Selected
Feature button.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Introduced in R2018b