sdynpy.fileio.sdynpy_psv.PolyFile

• Module: sdynpy.fileio.sdynpy_psv

• Source: GitHub

Signature¶

class sdynpy.fileio.sdynpy_psv.PolyFile(obj_or_path: 'str | PathLike[str] | Any') -> 'None'

High-level wrapper around a Polytec PSV file COM object.

Attributes¶

acquisition_mode¶

Active acquisition mode for the file.

acquisition_properties¶

Available acquisition-property wrappers for the active mode.

Returns¶

• dict[str, Any]

• Mapping from snake_case property names to wrapper objects. Singular

• COM properties are returned as wrapper instances; collection-valued

• COM properties are returned as tuples of wrapper instances.

alignments¶

Alignment information.

author¶

Document author.

camera_settings¶

Camera settings.

Raises¶

• NotImplementedError

• The COM object returned by this property is undocumented and is not

• wrapped by this module.

comments¶

Document comments.

contained_files¶

Contained files if this file is a combined file.

Raises¶

• ValueError

• If the file contains no embedded files.

date¶

File timestamp as returned by the COM interface.

elements¶

Geometry elements.

file_name¶

Path of the opened file.

hardware¶

Hardware information.

measurement_locations¶

Measurement locations.

Raises¶

• ValueError

• If no measurement locations are defined in the dataset.

measurement_points¶

Measurement points.

parent_file¶

Parent combined file containing this file.

Raises¶

• ValueError

• If this file has no parent combined file.

point_domains¶

Available point domains.

profiles¶

Profiles defined in the dataset.

Raises¶

• ValueError

• If no profiles are defined in the dataset.

scan_head_devices_info¶

Scan-head-device information.

spectrogram_info¶

Spectrogram information.

subject¶

Document subject.

textures¶

Textures associated with the dataset.

title¶

Document title.

version¶

Version metadata reported by the COM interface.

video_bitmap¶

Video bitmap information.

video_mapping_info¶

Video mapping information.

Methods¶

__init__¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.__init__(self, obj_or_path: 'str | PathLike[str] | Any') -> 'None'

Open a Polytec file or wrap an existing COM file object.

Parameters¶

• obj_or_path

• Either a filesystem path to a Polytec file, or an existing COM file

• object returned by the PolyFile COM interface.

Raises¶

• ModuleNotFoundError

• If pywin32 is not installed.

compute_alignment_error_map¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.compute_alignment_error_map(self, *, pixel_step: 'int' = 10, region_mode: 'str' = 'full', hull_buffer_pixels: 'float' = 0.0, scale_region_mode: 'str' = 'measpoint_hull', metric: 'str' = 'rms', distance0: 'float' = 0.0, distance1: 'float' = 1.0) -> 'dict[str, Any] | list[Any]'

Compute a sampled alignment-error field over the image.

Parameters¶

• pixel_step

• Sampling stride in pixels in both x and y directions.

• region_mode

• Region over which to compute the field. Supported values are:

• - "full"

• - "measpoint_hull"

• hull_buffer_pixels

• Optional outward buffer applied to the measurement-point convex hull.

• scale_region_mode

• Region used to determine colormap scaling values. Supported values:

• - "full"

• - "measpoint_hull"

• metric

• Error metric extracted from get_beam_intersection_at_pixel.

• Supported values:

• - "rms"

• - "mean"

• - "max"

• distance0, distance1

• Distances used to construct beam rays.

Returns¶

• dict[str, Any] | list[Any]

• For a normal file, returns a dictionary containing:

• - x_grid

• - y_grid

• - error

• - compute_mask

• - scale_mask

• - metric

• - region_mode

• - scale_region_mode

• - pixel_step

• - hull_points

• - vmin

• - vmax

• For a combined file, returns a list of per-contained-file results.

get_alignment2d_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_alignment2d_image(self, alignment_index: 'int | None' = None, *, mode: 'str' = 'matplotlib', color: 'str | None' = None, marker: 'str | None' = None, size: 'float' = 60.0, linewidth: 'float' = 2.0, show_labels: 'bool' = True, ax: 'Any' = None, title: 'str | None' = '2D Alignment Points') -> 'Any'

Plot 2D alignment points on the stored image.

For combined files, returns a list of per-contained-file results.

get_alignment3d_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_alignment3d_image(self, alignment_index: 'int | None' = None, *, mode: 'str' = 'matplotlib', color: 'str | None' = None, marker: 'str | None' = None, size: 'float' = 60.0, linewidth: 'float' = 2.0, show_labels: 'bool' = True, use_point_labels: 'bool' = True, ax: 'Any' = None, title: 'str | None' = '3D Alignment Points') -> 'Any'

Plot 3D alignment points on the stored image.

For combined files, returns a list of per-contained-file results.

get_alignment3d_quality¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_alignment3d_quality(self)

Returns the alignment quality for each laser head.

If the file contains multiple files, then one quality score will be returned for each contained file.

Returns¶

• quality : np.ndarray A 1D array for single-scan files and a 2D array for combined files. Each row in the 2D array represents a different scan.

get_alignment_error_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_alignment_error_image(self, *, pixel_step: 'int' = 10, region_mode: 'str' = 'full', hull_buffer_pixels: 'float' = 0.0, scale_region_mode: 'str' = 'measpoint_hull', metric: 'str' = 'max', distance0: 'float' = 0.0, distance1: 'float' = 1.0, cmap: 'str' = 'viridis', alpha: 'float' = 0.6, show_measurement_points: 'bool' = False, show_hull: 'bool' = False, ax: 'Any' = None, title: 'str | None' = None) -> 'Any'

Overlay a sampled alignment-error colormap on the stored image.

Parameters¶

• pixel_step

• Sampling stride in pixels.

• region_mode

• Region over which to compute the field:

• - "full"

• - "measpoint_hull"

• hull_buffer_pixels

• Optional outward buffer applied to the measurement-point convex hull.

• scale_region_mode

• Region used to set colormap scaling:

• - "full"

• - "measpoint_hull"

• metric

• Error metric to display:

• - "rms"

• - "mean"

• - "max"

• distance0, distance1

• Distances used to construct beam rays.

• cmap

• Matplotlib colormap name.

• alpha

• Overlay transparency.

• show_measurement_points

• Whether to overlay measurement-point positions.

• show_hull

• Whether to draw the convex hull polygon used for hull-based masking.

• ax

• Existing matplotlib axes to draw onto.

• title

• Plot title. If omitted, a default title is generated.

Returns¶

• Any

• For a normal file, returns (fig, ax, result_dict).

• For a combined file, returns a list of per-contained-file results.

get_beam_intersection_at_pixel¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_beam_intersection_at_pixel(self, x_pixel: 'float', y_pixel: 'float', *, distance0: 'float' = 0.0, distance1: 'float' = 1.0) -> 'dict[str, Any] | list[Any]'

Compute the least-squares beam intersection point at an image pixel.

Parameters¶

• x_pixel, y_pixel

• Image pixel coordinates.

• distance0, distance1

• Distances passed to Alignment3D.scanner_to_coord_3d to construct

• two points on each beam.

Returns¶

• dict[str, Any] | list[Any]

• For a normal file, returns a dictionary containing:

• - pixel_xy

• - video_xy

• - intersection

• - distances

• - rms_distance

• - mean_distance

• - max_distance

• - beam_rays

• For a combined file, returns a list of per-contained-file results.

Raises¶

• ValueError

• If fewer than two beam rays are available.

get_beam_rays_at_pixel¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_beam_rays_at_pixel(self, x_pixel: 'float', y_pixel: 'float', *, distance0: 'float' = 0.0, distance1: 'float' = 1.0) -> 'list[dict[str, Any]] | list[Any]'

Return beam origin and unit direction for each scan head at a pixel.

Parameters¶

• x_pixel, y_pixel

• Image pixel coordinates.

• distance0, distance1

• Distances passed to Alignment3D.scanner_to_coord_3d to construct

• two points along the beam. distance0 defines the origin point,

• and the vector from that point to the point at distance1 is

• normalized to produce the unit beam direction.

Returns¶

• list[dict[str, Any]] | list[Any]

• For a normal file, returns a list of dictionaries, one per matched

• 2D/3D alignment pair, containing:

• - alignment_index

• - video_xy

• - scanner_xy

• - origin

• - direction

• For a combined file, returns a list of per-contained-file results.

Raises¶

• ValueError

• If the number of 2D and 3D alignments does not match, or if a zero

• direction vector is encountered.

get_coherence¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_coherence(self, collapse_reference_signals: 'bool' = True) -> 'CoherenceArray'

Extract coherence functions from the active spectrum point domain.

Parameters¶

• collapse_reference_signals

• If True, signals identified as reference-channel signals are

• averaged across measurement points and returned as a single trace

• per signal. If False, all traces are returned individually.

Returns¶

• CoherenceArray

• An sdynpy coherence array produced by :func:coherence_array.

get_focus_status_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_focus_status_image(self, *, mode: 'str' = 'matplotlib', size: 'float' = 60.0, linewidth: 'float' = 2.0, show_labels: 'bool' = False, use_point_labels: 'bool' = True, ax: 'Any' = None, title: 'str | None' = 'Focus Status') -> 'Any'

Plot measurement points grouped by focus status.

For combined files, returns a list of per-contained-file results.

get_geometry¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_geometry(self) -> 'Geometry'

Build an sdynpy geometry object from measurement points and elements.

Measurement-point coordinates are converted into nodes, and simple element connectivity is inferred from element point-label counts: 2-point elements become tracelines, 3-point elements become type 61 elements, and 4-point elements become type 64 elements.

get_geometry_status_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_geometry_status_image(self, *, mode: 'str' = 'matplotlib', size: 'float' = 60.0, linewidth: 'float' = 2.0, show_labels: 'bool' = False, use_point_labels: 'bool' = True, ax: 'Any' = None, title: 'str | None' = 'Geometry Status') -> 'Any'

Plot measurement points grouped by geometry status.

For combined files, returns a list of per-contained-file results.

get_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_image(self) -> 'Image.Image | list[Any]'

Return the stored test image as a PIL image.

For combined files, returns a list of images from the contained files.

get_measpoint_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_measpoint_image(self, *, mode: 'str' = 'matplotlib', color: 'str' = 'red', marker: 'str' = 'o', size: 'float' = 40.0, linewidth: 'float' = 2.0, show_labels: 'bool' = False, use_point_labels: 'bool' = True, ax: 'Any' = None, title: 'str | None' = 'Measurement Points') -> 'Any'

Plot measurement-point locations on the stored image.

For combined files, returns a list of per-contained-file results.

get_multiple_coherence¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_multiple_coherence(self, collapse_reference_signals: 'bool' = True) -> 'MultipleCoherenceArray'

Extract multiple-coherence functions from the active spectrum point domain.

Parameters¶

• collapse_reference_signals

• If True, signals identified as reference-channel signals are

• averaged across measurement points and returned as a single trace

• per signal. If False, all traces are returned individually.

Returns¶

• MultipleCoherenceArray

• An sdynpy multiple-coherence array produced by

• :func:multiple_coherence_array.

get_power_spectral_densities¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_power_spectral_densities(self, data_type: 'str' = 'acceleration', collapse_reference_signals: 'bool' = True) -> 'PowerSpectralDensityArray'

Extract power spectral densities from the active spectrum point domain.

Parameters¶

• data_type

• Preferred quantity to extract from the signal name. Supported values

• are "displacement", "velocity", and "acceleration".

• collapse_reference_signals

• If True, signals identified as reference-channel signals are

• averaged across measurement points and returned as a single trace

• per signal. If False, all traces are returned individually.

Returns¶

• PowerSpectralDensityArray

• An sdynpy PSD array produced by

• :func:power_spectral_density_array.

get_scan_status_image¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_scan_status_image(self, *, mode: 'str' = 'matplotlib', size: 'float' = 60.0, linewidth: 'float' = 2.0, show_labels: 'bool' = False, use_point_labels: 'bool' = True, ax: 'Any' = None, title: 'str | None' = 'Scan Status') -> 'Any'

Plot measurement points grouped by scan status.

For combined files, returns a list of per-contained-file results.

get_scanner_coordinates_at_pixel¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_scanner_coordinates_at_pixel(self, x_pixel: 'float', y_pixel: 'float') -> 'list[dict[str, Any]] | list[Any]'

Return scanner coordinates for each 2D alignment at an image pixel.

Parameters¶

• x_pixel, y_pixel

• Image pixel coordinates.

Returns¶

• list[dict[str, Any]] | list[Any]

• For a normal file, returns a list of dictionaries, one per 2D

• alignment, containing:

• - alignment_index

• - video_xy

• - scanner_xy

• For a combined file, returns a list of per-contained-file results.

get_time_response¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_time_response(self, collapse_reference_signals: 'bool' = True) -> 'TimeHistoryArray'

Extract time histories from the active time-domain point domain.

Parameters¶

• collapse_reference_signals

• If True, signals identified as reference-channel signals are

• averaged across measurement points and returned as a single trace

• per signal. If False, all traces are returned individually.

Returns¶

• TimeHistoryArray

• An sdynpy time-history array produced by

• :func:time_history_array.

get_transfer_functions¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.get_transfer_functions(self, method: 'str' = 'h1', data_type: 'str' = 'acceleration', collapse_reference_signals: 'bool' = True) -> 'TransferFunctionArray'

Extract transfer functions from the active spectrum point domain.

Parameters¶

• method

• Transfer-function estimator to extract. Supported values are

• "h1" and "h2".

• data_type

• Response quantity to extract from the signal name. Supported values

• are "acceleration", "velocity", and "displacement".

• collapse_reference_signals

• If True, signals identified as reference-channel signals are

• averaged across measurement points and returned as a single trace

• per signal. If False, all reference-channel traces are returned

• individually.

Returns¶

• TransferFunctionArray

• An sdynpy transfer-function array produced by

• :func:transfer_function_array.

pixel_to_video¶

• Source: GitHub

def sdynpy.fileio.sdynpy_psv.PolyFile.pixel_to_video(self, x_pixel: 'float', y_pixel: 'float') -> 'tuple[float, float] | list[Any]'

Convert image pixel coordinates to Polytec video coordinates.

For combined files, returns a list of per-contained-file results.