FinderAPI

Overview

The FinderAPI module has functions to search through STEP files for specific aspects of the process, assemblies, and workpiece data. To loop through a process in order of execution, the Adaptive class may also be useful.

There is no need to create an instance of FinderAPI, it is just a namespace that collects related functions in one place as class methods.

get_probe_ball_radius/unit/bounds()

@classmethod
def get_probe_ball_radius(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_probe_ball_radius_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_probe_ball_radius_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_probe_ball_radius() functions describe the radius of the ball at the bottom of a touch probe tool object. If a workingstep object is passed in, the function will be applied to the probe selected for that workingstep.

The base function returns the numeric value. The unit of the value is returned by _unit function. The _bounds function returns a dictionary with the base value and unit, upper and lower recommended values along with reasons for each recommendation. Any of these values will be returned as None if they are not set.

get_probe_stylus_diameter/unit/bounds()

@classmethod
def get_probe_stylus_diameter(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_probe_stylus_diameter_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_probe_stylus_diameter_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_probe_stylus_diameter() functions describe the diameter of the stylus of a touch probe tool object. If a workingstep object is passed in, the function will be applied to the probe selected for that workingstep.

get_tool_all()

@classmethod
def get_tool_all(cls) -> List[Object]:

The get_tool_all() function returns a list of all tool objects in the AP-238 file.

get_tool_category()

@classmethod
def get_tool_category(cls,
	ws_or_tool: Object
	) -> str:

The get_tool_category() function returns a summary description of the type of a tool as a string name. The following categories are returned.

category = MILLING
category = DRILLING
category = PROBING
category = MISSING
category = UNKNOWN

Missing is returned if the workingstep has no tool and is in an error state. Unknown is returned if the tool does not belong to one of the currently recognized categories. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_coolant_through_tool()

@classmethod
def get_tool_coolant_through_tool(cls,
	ws_or_tool: Object
	) -> bool:

The get_tool_coolant_through_tool() function returns true if coolant through tool is supported, false if not, or None if the value is not set.

get_tool_corner_radius/unit/bounds()

@classmethod
def get_tool_corner_radius(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_corner_radius_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_corner_radius_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_corner_radius() functions describe the corner radius of a tool which is the parameter used for cutter radius compensation. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_current_corner_radius()

@classmethod
def get_tool_current_corner_radius(cls,
	ws_or_tool: Object
	) -> Tuple[float,float]

The get_tool_current_corner_radius() function returns a tuple containing the nominal and current corner radius of a tool. This current value may differ from the value defined by the CAM system because a different tool was selected or because of tool wear.

get_tool_current_diameter()

@classmethod
def get_tool_current_diameter(cls,
	ws_or_tool: Object
	) -> Tuple[float,float]

The get_tool_current_diameter() function returns a tuple containing the nominal and current diameter of a tool. This current value may differ from the value defined by the CAM system because a different tool was selected or because of tool wear.

get_tool_current_length()

@classmethod
def get_tool_current_length(cls,
	ws_or_tool: Object
	) -> Tuple[float,float]

The get_tool_current_length() function returns a tuple containing the nominal and current length of a tool. This current value may differ from the value defined by the CAM system because a different tool was selected or because of tool wear.

get_tool_diameter/unit/bounds()

@classmethod
def get_tool_diameter(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_diameter_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_diameter_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_diameter() functions describe the diameter of a tool which is the parameter used for cutter diameter compensation. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_drill_matching()

@classmethod
def get_tool_drill_matching(cls,
	diameter: float = 0,
	length: float = 0,
	tip_angle: float = 0,
	tooltype: str = None
	) -> List[Object]:

The get_tool_drill_matching() function returns a list of drill tool objects matching a set of values given as keyword pararmeters. See get_tool_mill_matching() for a similar operation on milling cutters.

For example, an application may require the tool to have a diameter and radius, but be willing to accept any length provided it is over a required minimium. In this case, can use the function to find tools with the diameter and radius, and the application programmer can filter the found tools for the minimum length using the get_tool_length() function.

Keyword Parameters

diameter: float = 0: The required effective_cutting_diameter, or zero if this parameter does not matter.
length: float = 0: The required functional length, or zero if this parameter does not matter.
tip_angle: float = 0: The required tip_angle, or zero if this parameter does not matter.
tooltype: str = None: The required type of tool, or None if the type does not matter.

get_tool_expected_life/unit/bounds()

@classmethod
def get_tool_expected_life(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_expected_life_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_expected_life_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_expected_life() functions describe the expected remaining life of the tool cutting component, usually in minutes. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_flute_count()

@classmethod
def get_tool_flute_count(cls,
	ws_or_tool: Object
	) -> float:

The get_tool_flute_count() function returns the number of flutes on a tool, or None if no value exists. The function returns a floating point value for when the flute count is fractional.

get_tool_flute_length/unit/bounds()

@classmethod
def get_tool_flute_length(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_flute_length_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_flute_length_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_flute_length() functions describe the flute length defined for a tool, which constrains the maximum depth of cut. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_functional_length/unit()

@classmethod
def get_tool_functional_length(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_functional_length_unit(cls,
	ws_or_tool: Object
	) -> Unit:

The get_tool_functional_length() functions returns the functional length defined for a tool. This length can be used for 5-axis cutter compensation. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

The base function returns the numeric value. The unit of the value is returned by _unit function.

get_tool_geometry_length_unit()

@classmethod
def get_tool_geometry_length_unit(cls,
	ws_or_tool: Object
	) -> Unit:

The get_tool_geometry_length_unit() functions returns the unit used for length measures in the tool geometry.

get_tool_hand_of_cut()

@classmethod
def get_tool_hand_of_cut(cls,
	ws_or_tool: Object
	) -> str:

The get_tool_hand_of_cut() function returns a string describing the hand of cut of a tool. The allowed values are left, right and neutral. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_horizontal_distance/unit()

@classmethod
def get_tool_horizontal_distance(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_horizontal_distance_unit(cls,
	ws_or_tool: Object
	) -> Unit:

The get_tool_horizontal_distance() functions returns the horizontal distance of a tool which is a rarely used parameter in APT files. The function assumes that the tool has been defined using the tool function of the APT API. STEP-NC supports a large range of other tool types. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

The base function returns the numeric value. The unit of the value is returned by _unit function.

get_tool_identifier()

@classmethod
def get_tool_identifier(cls,
	ws_or_tool: Object
	) -> str:

The get_tool_identifier() function returns the manufacturers name for a tool which may be different for the part name because the latter describes an instance and the former describes a category/type/sales item. The part name is more likely to be controlled by the user. The identifier is more likely to be controlled by the maker or vendor of the tool.

get_tool_iso13399_atts()

@classmethod
def get_tool_iso13399_atts(cls,
	ws_or_tool: Object
	) -> dict[str, Any]

The get_tool_iso13399_atts() function returns a dictionary of the ISO 13399 attributes found for the tool. ISO 13399 is a new standard for cutting tool data. ISO 13399 data is divided into numeric attributes that describe parametric properties of the tool such as the length and string attributes that describe other properties of the tool such as the hand_of_cut.

The functions finds the ISO 13399 data in a file with the name of the Tool identifier.

get_tool_length/unit/bounds()

@classmethod
def get_tool_length(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_length_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_length_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_length() functions describe the length of the tool, which is also known as the height in APT. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_material/standard()

@classmethod
def get_tool_material(cls,
	ws_or_tool: Object
	) -> str:

@classmethod
def get_tool_material_standard(cls,
	ws_or_tool: Object
	) -> str:

The get_tool_material() functions return a description of the material used in the cutting component of the tool and the standard that describes the material. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_mill_matching()

@classmethod
def get_tool_mill_matching(cls,
	diameter: float = 0,
	length: float = 0,
	radius: float = 0,
	flute_count: float = 0,
	tooltype: str = None
	) -> List[Object]:

The get_tool_mill_matching() function returns a list of tool objects matching a set of values given as keyword pararmeters. See get_tool_drill_matching() for a similar operation on drills.

Keyword Parameters

diameter: float = 0: The required effective_cutting_diameter, or zero if this parameter does not matter.
length: float = 0: The required functional length, or zero if this parameter does not matter.
radius: float = 0: The required corner radius, or zero if this parameter does not matter.
flute_count:: float = 0: The required number of flutes (can be a fraction), or zero if this parameter does not matter.
tooltype: str = None: The required type of tool, or None if the type does not matter.

get_tool_number()

@classmethod
def get_tool_number(cls,
	ws_or_tool: Object
	) -> str:

@classmethod
def get_tool_number_as_number(cls,
	ws_or_tool: Object
	) -> int:

The get_tool_number() functions returns the number of a tool which in APT programs corresponds to its position in the tool changer. This is returned as a string even though the value is typically numeric. The _as_number variant casts the value to an integer.

get_tool_overall_length/unit/bounds()

@classmethod
def get_tool_overall_length(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_overall_length_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_overall_length_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_overall_length() functions describe the overall assembly length defined for a tool, which describes the complete length of the tool and is used in collision detection algorithms. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_part_name()

@classmethod
def get_tool_part_name(cls,
	ws_or_tool: Object
	) -> str:

The get_tool_part_name() function returns the part name given to the geometry of the tool or None if there is no geometry defined for the tool. The tool part name is a third name for the tool derived from its geometry model (if it has one). The tool geometry is a workpiece like any other workpiece and like those other workpieces it has a part name.

A tool can have several names. The Tool number has become a name in the STEP-NC standard but for reasons having to do with legacy APT files for the time being applications will be safer if they continue to treat this attribute as a number. The Tool Identifier is a manufacturer’s name for the file that can be used to get data about the tool from a ISO 13399 database.

get_tool_recommended_feed/unit/bounds()

@classmethod
def get_tool_recommended_feed(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_recommended_feed_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_recommended_feed_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_recommended_feed() functions describe recommended feed rate for a tool. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_recommended_speed/unit/bounds()

@classmethod
def get_tool_recommended_speed(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_recommended_speed_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_recommended_speed_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_recommended_speed() functions describe the recommended spindle speed for a tool. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_similar()

@classmethod
def get_tool_similar(cls,
	ws_or_tool: Object,
	tooltype: bool = False,
	diameter: bool = False,
	length: bool = False,
	radius: bool = False,
	flute_count: bool = False,
	manufacturer: bool = False
	) -> List[Object]:

The get_tool_similar() function returns a list of tool objects with properties that match a given tool. When two AP238 data sets are merged, some tools may be redundant. This function can find tools with a required set of properties, then your code can check the other properties to see if they are within an acceptable range. The properties to match are indicated by boolean keyword arguments.

Keyword Parameters

ws_or_tool: Object: The tool that is to be the basis of the search. The tools in the return list will have the same values as this tool in the selected parameters.
tooltype: bool = false: If true, the similar tool must have the same type. If false, the type does not matter.
diameter: bool = false: If true, the similar tool must have the same effective_cutting_diameter.
length: bool = false: If true, the similar tool must have the same functional length
radius: bool = false: If true, the similar tool must have the same corner radius (which may be None for both tools).
flute_count: bool = false: If true, the similar tool must have the same number of flutes.
manufacturer: bool = false: If true, the similar tool must have the same manufacturer.

get_tool_taper_angle/unit/bounds()

@classmethod
def get_tool_taper_angle(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_taper_angle_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_taper_angle_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_taper_angle() functions describe the angle of the tool taper. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_technology()

@classmethod
def get_tool_technology(cls,
	tool: Object
	) -> List[Object]:

The get_tool_technology() function returns a list of all technology objects (which describe speeds and feeds) that are used with a given tool.

get_tool_thread_form_type()

@classmethod
def get_tool_thread_form_type(cls,
	ws_or_tool: Object
	) -> str:

The get_tool_thread_form_type() functions describe the thread form type of a tapping tool. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_thread_pitch/unit/bounds()

@classmethod
def get_tool_thread_pitch(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_thread_pitch_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_thread_pitch_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_thread_pitch() functions describe the thread pitch of a tapping tool. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_thread_size/unit/bounds()

@classmethod
def get_tool_thread_size(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_thread_size_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_thread_size_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_thread_size() functions describe the thread size of a tapping tool. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_thread_taper_count()

@classmethod
def get_tool_thread_taper_count(cls,
	ws_or_tool: Object
	) -> float:

The get_tool_thread_form_type() functions describe the thread taper count of a tapping tool. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_tip_angle/unit/bounds()

@classmethod
def get_tool_tip_angle(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_tip_angle_unit(cls,
	ws_or_tool: Object
	) -> Unit:

@classmethod
def get_tool_tip_angle_bounds(cls,
	ws_or_tool: Object
	) -> {
	value: float,
	unit: Unit,
	lower: float,
	lower_reason: str,
	upper: float,
	upper_reason: str
	}

The get_tool_tip_angle() functions describe the angle of the tool tip. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

get_tool_type()

@classmethod
def get_tool_type(cls,
	ws_or_tool: Object
	) -> str:

The get_tool_type() function returns the type of the tool as a string name.

get_tool_using_identifier()

@classmethod
def get_tool_using_identifier(cls,
	mfg_id: str
	) -> Object:

The get_tool_using_identifier() function returns the first tool or probe found with the given identifier. In this case the identifier is the manufacturer's name for the category of the tool which may be different from the part name which descirbes a single instance of the tool.

get_tool_using_number()

@classmethod
def get_tool_using_number(cls,
	num_id: str
	) -> Object:

The get_tool_using_number() function returns the first tool or probe found with the given identifier. In this case the identifier is the number of a tool, which usually corresponds to the position of that tool in the tool changer and should be unique but this is not required.

get_tool_using_workpiece()

@classmethod
def get_tool_using_workpiece(cls,
	workpiece: Object
	) -> Object:

The get_tool_using_workpiece() function returns the first tool or probe that uses the given workpiece to define its geometry.

get_tool_vertical_distance/unit()

@classmethod
def get_tool_vertical_distance(cls,
	ws_or_tool: Object
	) -> float:

@classmethod
def get_tool_vertical_distance_unit(cls,
	ws_or_tool: Object
	) -> Unit:

The get_tool_vertical_distance() functions returns the vertical distance of a tool which is a rarely used parameter in APT files. The function assumes that the tool has been defined using the tool function of the APT API. STEP-NC supports a large range of other tool types. If a workingstep object is passed in, the function will be applied to the tool selected for that workingstep.

The base function returns the numeric value. The unit of the value is returned by _unit function.

get_tool_workpiece()

@classmethod
def get_tool_workpiece(cls,
	ws_or_tool: Object
	) -> Object:

The get_tool_workpiece() function returns the workpiece that defines the geometry of the tool. The workpiece maybe a single part or an assembly. The workpiece may have tolerances defined.

set_api_units()

def set_api_units(cls,
	system: Unit = UNKNOWN,
	feed: Unit = UNKNOWN,
	speed: Unit = UNKNOWN
	) -> None:

The set_api_units() function sets the unit preferences for values passed in and out of the API. When returning values, they will be converted from whatever unit is specified in the STEP data into the desired unit. Using keyword arguments, you can set a unit system which controls many kinds of value as well as override the units for several others.

Keyword Parameters

system: Unit = UNKNOWN: Set the unit system for length, feedrate, spindle speed, power and torque. By default, these values are all AS_IS. If set to IN, lengths are inch, feed is inch per minute (ipm), spindle speed is RPM, power is horse power (hp), and torque is pound foot. If set to MM, lengths are millimeter, feed is millimeters per minute (mmpm), spindle speed is RPM, power is kilowatt (kw), and torque is Newton meter.
feed: Unit = UNKNOWN: Set the unit preference for feedrate values. Acceptable linear velocity units are MMPS, MMPM, CMPS, MPS, IPS, IPM, FPS, and FPM.
speed: Unit = UNKNOWN: Set the unit preference for spindle speed values. Acceptable rotational velocity units are RPM and HERTZ.