p21 - STEP-file¶
STEP physical file representation (STEP-file) specified by the ISO 10303-21 standard.
STEP-File is data exchange form of STEP. ISO 10303 can represent 3D objects in Computer-aided design (CAD) and related information. Due to its ASCII structure, a STEP-file is easy to read, with typically one instance per line. The format of a STEP-File is defined in ISO 10303-21 Clear Text Encoding of the Exchange Structure.
ISO 10303-21 defines the encoding mechanism for representing data conforming to a particular schema in the EXPRESS data modeling language specified in ISO 10303-11. A STEP-File is also called p21-File and STEP Physical File. The file extensions .stp and .step indicate that the file contains data conforming to STEP Application Protocols while the extension .p21 should be used for all other purposes.
Source: https://en.wikipedia.org/wiki/ISO_10303-21
The intended usage is to import the p21
module and create new objects by factory functions:
from steputils import p21
FNAME = "example.p21"
# Create a new STEP-file:
stepfile = p21.new_step_file()
# Create a new data section:
data = stepfile.new_data_section()
# Add entity instances to data section:
data.add(p21.simple_instance('#1', name='APPLICATION', params=('MyApp', 'v1.0')))
# Set required header entities:
stepfile.header.set_file_description(('Example STEP file', 'v1.0'))
stepfile.header.set_file_name(name=FNAME, organization=('me', 'myself'), autorization='me')
stepfile.header.set_file_schema(('NONE',))
# Write STEP-file to file system:
stepfile.save(FNAME)
# Read an existing file from file system:
try:
stepfile = p21.readfile(FNAME)
except IOError as e:
print(str(e))
except ParseError as e:
# Invalid STEP-file
print(str(e))
else:
print(f'File {FNAME} is a valid STEP-file')
Loader Functions¶
-
steputils.p21.
readfile
(filename: str) → StepFile¶ Read STEP-file (ISO 10303-21) filename from file system.
-
steputils.p21.
load
(fp: TextIO) → StepFile¶ Load STEP-file (ISO 10303-21) from text stream.
A special encoding form characters > 126 is applied in STEP-Files, therefore an encoding setting at opening files is not necessary, reading as
'ascii'
works fine. Decoding of this special characters will be applied.Parameters: fp – STEP-file content as text stream yielding unicode strings
-
steputils.p21.
loads
(s: str) → StepFile¶ Load STEP-file (ISO 10303-21) from unicode string.
Decoding for special characters > 126 to unicode characters according to ISO 10303-21 standard will be applied.
Parameters: s – STEP-file content as unicode string
Factory Functions¶
-
steputils.p21.
simple_instance
(ref: str, name: str, params) → SimpleEntityInstance¶ Factory function to create a new
SimpleEntityInstance
object. This method creates theEntity
object automatically.Parameters: - ref – instance reference as
str
orReference
object. - name – entity name as str or
Keyword
object - params – entity parameters as
tuple
,list
orParameterList
- ref – instance reference as
-
steputils.p21.
simple_entity_instance
(ref: str, entity:Entity) → SimpleEntityInstance¶ Factory function to create a new
SimpleEntityInstance
object.Parameters:
-
steputils.p21.
complex_entity_instance
(ref: str, entities: List[Entity]) → ComplexEntityInstance¶ Factory function to create a new
ComplexEntityInstance
object.Parameters:
-
steputils.p21.
entity
(name: str, params) → Entity¶ Factory function to create a new
Entity
object.Parameters: - name – entity name as str or
Keyword
object - params – entity parameters as
tuple
,list
orParameterList
- name – entity name as str or
-
steputils.p21.
keyword
(name: str) → Keyword¶ Factory function to create a new
Keyword
object. Only uppercase letters an digits are allowed, standard keyword has to start with an uppercase letter an user defined keyword has to start with'!'
.
-
steputils.p21.
reference
(ref: str) → Reference¶ Factory function to create a new
Reference
object (Entity Instance Name). A reference has to start with'#'
followed by only digits e.g.'#100'
-
steputils.p21.
parameter_list
(*args) → ParameterList¶ Factory function to create a new
ParameterList
object.
-
steputils.p21.
unset_parameter
(char: str) → UnsetParameter¶ Factory function to create a new
UnsetParameter
object. Unset attribute values are given as'$'
. Explicit attributes which got re-declared as derived in a subtype are encoded as'*'
in the position of the supertype attribute.
-
steputils.p21.
typed_parameter
(type_name: str, param) → TypedParameter¶ Factory function to create a new
TypedParameter
object.Parameters: - type_name – type name as
str
orKeyword
object. - param – typed parameter
- type_name – type name as
-
steputils.p21.
enum
(enum: str) → Enumeration¶ Factory function to create a new
Enumeration
object. A enumeration is surrounded'.'
and only uppercase letters and digits are allowed e.g.'.TRUE.'
or'.FALSE.'
.
-
steputils.p21.
binary
(value: int, unset: int = 0) → Binary¶ Factory function to create a new
Binary
object. Only for export used, unset specifies the uppermost unset bits.
-
steputils.p21.
timestamp
() → str¶ Factory function returns an ISO formatted UTC timestamp.
Type Checker Functions¶
-
steputils.p21.
is_string
(e) → bool¶ Returns
True
if e is astr
.
-
steputils.p21.
is_integer
(e) → bool¶ Returns
True
if e is anint
.
-
steputils.p21.
is_real
(e) → bool¶ Returns
True
if e is afloat
.
-
steputils.p21.
is_reference
(e) → bool¶ Returns
True
if e is anEntityInstanceName
.
-
steputils.p21.
is_enum
(e) → bool¶ Returns
True
if e is anEnumeration
.
-
steputils.p21.
is_unset_parameter
(e) → bool¶ Returns
True
if e is an unset or omitted parameter (UnsetParameter
).
-
steputils.p21.
is_typed_parameter
(e) → bool¶ Returns
True
if e is aTypedParameter
.
-
steputils.p21.
is_parameter_list
(e) → bool¶ Returns
True
if e is aParameterList
.Note: It is a single parameter if it’s not a
ParameterList
-
steputils.p21.
is_simple_entity_instance
(e) → bool¶ Returns
True
if e is aSimpleEntityInstance
.
-
steputils.p21.
is_complex_entity_instance
(e) → bool¶ Returns
True
if e is aComplexEntityInstance
.
Classes¶
Create new instances by the associated factory function!
StepFile¶
-
class
steputils.p21.
StepFile
¶ STEP physical file representation (STEP-file). Create new STEP-files by factory function
new_step_file()
.A STEP-File has one
HeaderSection
, and at least oneDataSection
.-
header
¶ Header section as
HeaderSection
object.
-
data
¶ List of data sections as
DataSection
objects
-
__getitem__
(ref: Reference) → EntityInstance¶ Returns
EntityInstance
by instance name ref. Searches all data sections if more than one exist.Parameters: ref – entity instance name as string e.g. '#100'
Raises: KeyError
– instance id not found
-
__iter__
() → Iterable[EntityInstance]¶ Returns iterable of all instance entities of all data sections.
-
__len__
() → int¶ Returns count of all stored entity instances.
-
__str__
() → str¶ Serialize to a STEP-file (ISO 10303-21) formatted
str
.Special encoding for characters > 126 into characters < 127 as unicode compatible characters according to ISO 10303-21 standard will be applied.
-
get
(ref: Reference) → Optional[EntityInstance]¶ Returns
EntityInstance
by instance name ref orNone
if not found. Searches all data sections if more than one exist.Parameters: ref – entity instance name as string e.g. '#100'
-
new_data_section
(params: Iterable = None) → DataSection¶ Create a new
DataSection
and append to existing data sections.
-
append
(data: DataSection) → None¶ Append new data section data.
Parameters: data – data section
-
save
(name: str) → None¶ Export STEP-file to the file system.
-
write
(fp: TextIO) → None¶ Serialize to a STEP-file (ISO 10303-21) formatted stream to
fp
(awrite()
-supporting file-like object).File encoding should be
'iso-8859-1'
but can also be'ascii'
, because ISO 10303-21 requires special encoding for characters > 126 into characters < 127 as unicode compatible characters, which should be compatible with most encodings, but don’t use 16-bit encodings!Parameters: fp – text stream
-
has_reference
(ref: str) → bool¶ Returns True if reference ref exist in any data section.
-
HeaderSection¶
The HEADER section has a fixed structure consisting of 3 to 6 groups in the given order. Except for the data fields time_stamp and FILE_SCHEMA all fields may contain empty strings.
FILE_DESCRIPTION(description: ParameterList, implementation_level: str)
description
implementation_level
: The version and conformance option of this file. Possible versions are “1” for the original standard back in 1994,'2'
for the technical corrigendum in 1995 and “3” for the second edition. The conformance option is either'1'
for internal and'2'
for external mapping of complex entity instances. Often, one will find here the value'2;1'
. The value'2;2'
enforcing external mapping is also possible but only very rarely used. The values'3;1'
and'3;2'
indicate extended STEP-Files as defined in the 2001 standard with several DATA sections, multiple schemas andFILE_POPULATION
support.
FILE_NAME(name: str, time_stamp: str, author: str, organization: ParameterList,
preprocessor_version: ParameterList, originating_system: str, authorization: str)
name
of this exchange structure. It may correspond to the name of the file in a file system or reflect data in this file. There is no strict rule how to use this field.time_stamp
indicates the time when this file was created. The time is given in the international data time format ISO 8601, e.g. 2003-12-27T11:57:53 for 27 of December 2003, 2 minutes to noon time.author
the name and mailing address of the person creating this exchange structureorganization
the organization to whom the person belongs topreprocessor_version
the name of the system and its version which produces this STEP-fileoriginating_system
the name of the system and its version which originally created the information contained in this STEP-file.authorization
the name and mailing address of the person who authorized this file.
FILE_SCHEMA(schema: ParameterList)
- Specifies one or several Express schema governing the information in the data section(s). For first edition files, only one EXPRESS schema together with an optional ASN.1 object identifier of the schema version can be listed here. Second edition files may specify several EXPRESS schema.
The last three header groups are only valid in second edition files.
FILE_POPULATION(governing_schema: str, determination_method: str, governed_sections: ParameterList)
(?)Indicating a valid population (set of entity instances) which conforms to an EXPRESS schemas. This is done by collecting data from several data_sections and referenced instances from other data sections.
governing_schema
, the EXPRESS schema to which the indicated population belongs to and by which it can be validated.determination_method
to figure out which instances belong to the population. Three methods are predefined:'SECTION_BOUNDARY'
,'INCLUDE_ALL_COMPATIBLE'
, and'INCLUDE_REFERENCED'
.governed_sections
, the data sections whose entity instances fully belongs to the population.The concept of FILE_POPULATION is very close to schema_instance of SDAI. Unfortunately, during the Standardization process, it was not possible to come to an agreement to merge these concepts. Therefore, JSDAI adds further attributes to FILE_POPULATION as intelligent comments to cover all missing information from schema_instance. This is supported for both import and export.
SECTION_LANGUAGE(language: str)
(?)HeaderSection[‘SECTION_LANGUAGE’] allows assignment of a default language for either all or a specific data section. This is needed for those Express schemas that do not provide the capability to specify in which language string attributes of entities such as name and description are given.
SECTION_CONTEXT(context: ParameterList)
(?)Provide the capability to specify additional context information for all or single data sections. This can be used e.g. for STEP-APs to indicate which conformance class is covered by a particular data section.
-
class
steputils.p21.
HeaderSection
¶ A
StepFile
has always one header section as attributeStepFile.header
.-
__getitem__
(name: str) → Entity¶ Returns header entry by name, raise
KeyError
if not found.
-
get
(name: str) → Optional[Entity]¶ Returns header entry by name or
None
if not found.
-
add
(self, entity: Entity) → None¶ Add or replace header entry.
-
set_file_description
(description: Tuple = None, level: str = '2;1') → None¶
-
set_file_name
(name: str, time_stamp: str = None, author: str = '', organization: Tuple = None, preprocessor_version: Tuple = None, organization_system: str = '', autorization: str = '') → None¶
-
set_file_schema
(schema: Tuple) → None¶
-
DataSection¶
The DATA section contains application data according to one specific express schema. The encoding of this data follows some simple principles.
Source of Documentation: https://en.wikipedia.org/wiki/ISO_10303-21
Every entity instance in the exchange structure is given a unique name in the form
'#1234'
. The instance name must consist of a positive number (>0) and is typically smaller than 263. The instance name is only valid locally within the STEP-file. If the same content is exported again from a system the instance names may be different for the same instances. The instance name is also used to reference other entity instances through attribute values or aggregate members. The referenced instance may be defined before or after the current instance.Instances of single entity data types are represented by writing the name of the entity in capital letters and then followed by the attribute values in the defined order within parentheses. See e.g.
#16=PRODUCT(...)
above.Instances of complex entity data types are represented in the STEP file by using either the internal mapping or the external mapping. External mapping has always to be used if the complex entity instance consist of more than one leaf entity. In this case all the single entity instance values are given independently from each other in alphabetical order as defined above with all entity values grouped together in parentheses. Internal mapping is used by default for conformance option 1 when the complex entity instance consists of only one leaf entity. The encoding is similar to the one of a single entity instance with the additional order given by the subtype definition.
Mapping of attribute values:
Only explicit attributes get mapped. Inverse, Derived and re-declared attributes are not listed since their values can be deduced from the other ones. Unset attribute values are given as
$
. Explicit attributes which got re-declared as derived in a subtype are encoded as*
in the position of the supertype attribute.Mapping of other data types:
Enumeration, boolean and logical values are given in capital letters with a leading and trailing dot such as
.TRUE.
. String values are given in'
. For characters with a code greater than 126 a special encoding is used. The character sets as defined in ISO 8859 and 10646 are supported. Note that typical 8 (e.g. west European) or 16 (Unicode) bit character sets cannot directly be taken for STEP-file strings. They have to be decoded in a very special way. Integers and real values are used identical to typical programming languages Binary values (bit sequences) are encoded as hexadecimal and surrounded by double quotes, with a leading character indicating the number of unused bits (0, 1, 2, or 3) followed by uppercase hexadecimal encoding of data. It is important to note that the entire binary value is encoded as a single hexadecimal number, with the highest order bits in the first hex character and the lowest order bits in the last one. The elements of aggregates (SET, BAG, LIST, ARRAY) are given in parentheses, separated by,
. Care has to be taken for select data types based on defined data types. Here the name of the defined data type gets mapped too.
-
class
steputils.p21.
DataSection
¶ A
StepFile
has alist
of data sections as attributeStepFile.data
. A new STEP-file has no data sections, create at least one by factory functionStepFile.new_data_section()
.-
instances
¶ Ordered dict of all entity instances of this data section. Key is the name of instance as a string (e.g.
'#100'
), values areEntityInstance
objects.
-
__getitem__
(ref: str) → EntityInstance¶ Returns instance by ref, raise
KeyError
if not found.
-
__iter__
()¶ Returns iterable of all instances in this data section.
-
get
(ref: str) → Optional[EntityInstance]¶ Returns instance by ref of
None
if not found.
-
__len__
() → int¶ Returns count of instances.
-
references
() → Iterable[Reference]¶ Returns iterable of entity instance names.
-
add
(instance: EntityInstance) → None¶ Append new entity instance. Replaces existing instances with same instance name if already exists.
Parameters: instance – entity instance
-
Helper Classes¶
-
class
steputils.p21.
ParameterList
¶ Typing helper class for parameter list.
-
class
steputils.p21.
Reference
¶ Typing helper class for entity instance name.
-
class
steputils.p21.
Keyword
¶ Typing helper class for keyword.
-
class
steputils.p21.
Enumeration
¶ Typing helper class for enumeration.
-
class
steputils.p21.
Binary
(value: int, unused: int = 0)¶ Binary type for exporting, loaded binary data is converted to int automatically.
-
value
¶ Value as
int
.
-
unset
¶ Count of unset bits in the range from 0 to 3.
-
-
class
steputils.p21.
UnsetParameter
¶ Typing helper class for unset parameter.
-
class
steputils.p21.
TypedParameter
(name: str, param)¶ Typed parameter, type_name is the type of the parameter, param is the parameter itself.
-
param
¶
-
-
class
steputils.p21.
Entity
(name: str, params: Union[Tuple, List[T], steputils.p21.ParameterList])¶ STEP-file entity, name is the type of the entity, params are the entity parameters as a
ParameterList
.-
params
¶ Entity parameters as
ParameterList
.
-