External Reference Files

Reference files can be read in two ways. In order to read the supported elements stored in reference files, the reader parameter Read Elements From Reference Files checkbox has to be enabled. For this method of reading, the following is true: All the reference files inherit the working units and offsets from the parent file and their respective units and offsets are ignored. The V8 reader can read both V7 and V8 references, whereas V7 will read only V7 references. Both V7 and V8 can read nested references. The nesting can be restricted to specific levels by setting the Max Depth of Reference Files to Read. References from the root dataset are considered level 1, and nested references are considered further levels.

Alternatively or in addition, when the parameter Keep Elements That Represent Reference Files checkbox is enabled, the V8 reader is able to read reference files as individual features with an igds_type of igds_xref. These features are a non-graphical representation of the XREF elements themselves, not the elements stored within the referenced files.

An external reference file is referred to by a path. If the V8 reader is unable to find a reference file at the path that is stored, it will make a secondary check for a file of the same name in the same folder as the source dataset, which may then be read as the reference file. The value of the igds_xref_file_path attribute reflects the path that is actually used, not the path that was stored. In contrast, the igds_linkage{}.string attribute, which generally exists for external reference file elements, is not altered on read, and will reflect the path which is stored in the file, regardless of whether it exists.

The V8 writer can create external reference elements in two ways:

  • When the V8 writer uses a seed file, the external reference file elements in the seed file are preserved and put into the destination dataset.
  • When features with an igds_type of igds_xref are given to the V8 writer, it will create an XREF element to establish an external reference for the destination dataset. If the same external reference file is to be created by both a feature and the seed file, the V8 writer will prefer the element from the seed file.

The IGDS V7 writer will also preserve external reference elements from the seed file to the destination dataset. It does not support writing of igds_xref elements from FME features.

Note that it is not required for features with igds_type of igds_xref to be written, if they are referenced by the seed file or its references. It is also not required for such reference features to be written if they are nested references from root level external references. Basically, if the root level external references are written or kept in a destination dataset from a seed file, all levels of external references will exist in the destination. In fact, nested reference features which do not have an igds_xref_parent_path which indicate that it represents a root level reference, then the feature will be skipped for writing.

An external reference element has the attributes shown below.

Attribute Name

Contents

igds_xref_camera_focal_len

The focal length value for the camera used for the view of the external file reference data.

Range: Real Number

Default: 0.0

igds_xref_camera_pos_x

The position in the x dimension for the camera used for the view of the external reference file data.

Range: Real Number

Default: 0.0

igds_xref_camera_pos_y

The position in the y dimension for the camera used for the view of the external reference file data.

Range: Real Number

Default: 0.0

igds_xref_camera_pos_z

The position in the z dimension for the camera used for the view of the external reference file data.

Range: Real Number

Default: 0.0

igds_xref_desc

The description of the external reference file.

Range: String

Default: No default

igds_xref_file_build_opts

The file builder option mask for the external reference file.

Range: Integer

Default: 15

igds_xref_file_disp_opts

The file displayer option mask for the external reference file.

Range: Integer

Default: 73858

igds_xref_file_name

The filename of the external reference file. This is a basename and extension, not a path.

This attribute is also added to elements read from external reference files, to identify their source file.

This attribute is required for writing external reference file elements.

Range: String

Default: No default

igds_xref_file_num

The file number for the external reference file.

Range: Integer

Default: 1

igds_xref_group_id

The number of the group to which this external reference file belongs.

Range: Integer

Default: 0

igds_xref_master_origin_x

The x dimension value for the origin of the external reference file position in master file UORs.

Range: Real Number

Default: 0.0

igds_xref_master_origin_y

The y dimension value for the origin of the external reference file position in master file UORs.

Range: Real Number

Default: 0.0

igds_xref_master_origin_z

The z dimension value for the origin of the external reference file position in master file UORs.

Range: Real Number

Default: 0.0

igds_xref_model_name

The name of the model of the external reference file. This value may be empty for the default model.

Range: String

Default: No default

igds_xref_name

The logical name of the external reference file. This value may distinguish between multiple references to the same reference file.

Range: String

Default: No default

igds_xref_nest_depth

The depth of nested reference of the external reference file.

Range: 0..65536

Default: 0

igds_xref_parent_attach_id

The id of the parent attachment of the external reference file.

Range: Numeric string

Default: “0”

igds_xref_parent_file_path (V8 only)

The file path of the parent file for an external reference file. It is added to features which represent external reference file elements (those with the an igds_type of igds_xref). This attribute is also added to elements read from an external reference file, to identify which file has referenced the external reference file. This attribute affects the writing of elements which represent external reference files. If this attribute value matches the value of igds_dataset of a feature with an igds_type of igds_xref, then an external reference file element will be written. Otherwise, it is not a root level reference, and will be skipped on write.

Range: String

Default: No default

igds_xref_path

The file path of the external reference file.

This attribute is also added to elements read from external reference files, to identify their source file.

This attribute is required for writing external reference file elements.

Note that on write, this attribute takes precedence over any linkage string that similarly represents the an xref path.

Range: String

Default: No default

igds_xref_reference_origin_x

The x dimension value for the origin of the external reference file position in reference UORs.

Range: Real Number

Default: 0.0

igds_xref_reference_origin_y

The y dimension value for the origin of the external reference file position in reference UORs.

Range: Real Number

Default: 0.0

igds_xref_reference_origin_z

The z dimension value for the origin of the external reference file position in reference UORs.

Range: Real Number

Default: 0.0

igds_xref_rotation

The rotation value for the external reference file.

Range: Real Number

Default: 0.0

igds_xref_scale

The conversion factor value for the external reference file.

Range: Real Number

Default: 1.0

igds_xref_version

The version number value for the external reference file.

Range: Integer

Default: 1

igds_xref_z_back

The back z clip value for the external reference file.

Range: Real Number

Default: 0.0

igds_xref_z_front

The front z clip value for the external reference file.

Range: Real Number

Default: 0.0