Threads¶

Threads are extracted from techincal drawings when you ask for variant measures. Rather than "just" obtaining the label of the Thread (e.g. M5), you also obtain additional information, such as Pitch, Threads per Inch, Length of the thread or Gender. This information is directly extracted from the Drawing itself and made available to you as JSON document.

Information¶

Thread interpretation contain a lot of information that allow you to make educated decisions on the feasibility or cost of a specific thread.

Quantity (int)¶

When a Thread label indicates multiple threads, the quantity attribute is set accordingly. For example 3xM5 would cause the quantity to be set to 3. By default the quantity is set to 1.

Gender (W24Gender)¶

Our API determines whether the Thread is located on the outside (male thread) or the inside (female thread) of the work piece. When the gender cannot be determined a null value is returned.

Length (Decimal)¶

The length of the Thread is available as Decimal value. The Length here indicates the length of the thread. The information is directly extracted from the drawing and put into context with the thread length specified in the thread label.

Thread Parameters¶

The following attributes are however guaranteed for all thread types:

• Blurb
• Diameter
• Unit
• Pitch
• Threads Per Inch
• Handedness
• Multi-start
• Length

Blurb (str)¶

The blurb is a simple string representation of the ThreadLabel for human consumption. Examples include: "M5, #1-64 UNC, G0.25"

Diameter (Decimal)¶

The diameter indicates the Major Diameter (i.e., not the Pitch Diameter) of the Thread in Millimeter. For Inch-based thread systems, this value is automatically converted.

Unit¶

Unit of the diameter. Currently this is always Millimeter. Future releases will allow the user to specify the desired unit system when creating the request

Pitch (Optional[Decimal])¶

Pitch of the Thread. For ISO-metric threads, the pitch is either explicitly stated on the Label, or implicitly given in the ISO standard. When the pitch is only implicitly provided, we automatically obtain the value specified in the standard. There are however cases where the lookup is not explicitly possible (e.g., when the norm specified a range of possible pitches and it would have been the designer's responsibility to explicitly specify one). In these cases a null value is returned.

For UTS and Whitworth Threads, the pitch is automatically calculated from the threads_per_inch value.

Threads Per Inch (Optional[Decimal])¶

Corresponding to the Threads Per Inch in the ISO standards, ANSI/ASME use the concept of threads_per_inch. This value is either directly derived from the thread label or for ISO-metric threads converted from the pitch

Handedness (W24ThreadHandedness)¶

Unless otherwise specified, threads are right-handed. When a thread is specified as left-handed (e.g., through the addition of a LH suffix), the Handedness is set to LEFT.

Overview of Thread Systems¶

The following Thread Systems are currently interpreted and returned accordingly.

W24ThreadISOMetric¶

When dealing with ISO-metric threads, the following additional attributes are available:

• Female/Male Major Diameter Tolerance
• Female/Male Pitch Diameter Tolerance

Female / Male Major Diameter Tolerance¶

Tolerance Class for the major diameter in accordance with ISO 965-1. None if the major diameter tolerance class is neither defined in the standard not explicitly specified.

Female/Male Pitch Diameter Tolerance¶

Tolerance Class for the pitch diameter in accordance with ISO 965-1. None if the pitch diameter tolerance class is neither defined in the standard not explicitly specified.

Example Response¶

Example response for the label "M5↧10/12"

[
    {
        "confidence": 0.9852090188334259,
        "label": {
            "blurb": "M5\u00d70.8\u20146g/6H\u00d710/12",
            "chamfer": null,
            "depth": {
                "blurb": "10",
                "depth": 10,
                "through_type": null
            },
            "quantity": 1,
            "size": {
                "blurb": "5",
                "nominal_size": 5,
                "size_type": "NOMINAL",
                "unit": null
            },
            "size_tolerance": {
                "blurb": "",
                "deviation_lower": null,
                "deviation_upper": null,
                "standard": null,
                "standard_class": null,
                "tolerance_grade": null,
                "toleration_type": "GENERAL_TOLERANCES"
            },
            "test_dimension": null,
            "thread": {
                "blurb": "M5\u00d70.8\u20146g/6H\u00d710/12",
                "diameter": 5,
                "handedness": "RIGHT",
                "length": 12,
                "multi_start": {
                    "number_of_starts": 1,
                    "thread_lead": null
                },
                "pitch": 0.8,
                "thread_type": "ISO_METRIC",
                "threads_per_inch": 31.75,
                "unit": "MILLIMETER"
            },
            "unit": null
        },
        "measure_id": "ed0d31d9-2bc7-4e86-8b4a-5a71c4b4fb84",
        "position": {
            "canvas": [
                {
                    "x": 0.48002385211687537,
                    "y": 0.5028371890004365
                },
                {
                    "x": 0.4949314251639833,
                    "y": 0.5028371890004365
                }
            ],
            "sectional": [
                {
                    "x": 0.7335329341317365,
                    "y": 0.4332688588007737
                },
                {
                    "x": 0.8083832335329342,
                    "y": 0.4332688588007737
                }
            ],
            "sheet": [
                {
                    "x": 0.48093665565896127,
                    "y": 0.5015303891560997
                },
                {
                    "x": 0.4959471630141099,
                    "y": 0.5015303891560997
                }
            ]
        },
        "warnings": []
    }
]

W24ThreadUTS¶

When dealing with UTS threads, the following additional attributes are available:

• UTS size
• UTS series

UTS Size (str)¶

UTS size as string representation.

Threads with a diameter < 0.25 inch are written with a leading '#'. Threads with a diameter >= 0.25 inch are represented as fractions with a tailing '"'

Examples: #0, 1 3/4"

UTS Series¶

UTS Format series following ASME B1.1 2003. Valid values include UNC UNF, UNRF, UNF, UN

Example Response¶

Example response for the label #3-48 UNC

{
    "confidence": 0.9763001,
    "label": {
        "blurb": "0.099\u201448 UNC\u20142A",
        "chamfer": null,
        "depth": null,
        "quantity": 1,
        "size": {
            "blurb": "0.099",
            "nominal_size": 0.099,
            "size_type": "NOMINAL",
            "unit": null
        },
        "size_tolerance": {
            "blurb": "",
            "deviation_lower": null,
            "deviation_upper": null,
            "standard": null,
            "standard_class": null,
            "tolerance_grade": null,
            "toleration_type": "GENERAL_TOLERANCES"
        },
        "test_dimension": null,
        "thread": {
            "blurb": "0.099\u201448 UNC\u20142A",
            "diameter": 0.099,
            "handedness": "RIGHT",
            "length": null,
            "multi_start": {
                "number_of_starts": 1,
                "thread_lead": null
            },
            "pitch": 0.5291666666666667,
            "thread_type": "UTS",
            "threads_per_inch": 48,
            "unit": "INCH"
        },
        "unit": null
    },
    "measure_id": "33e1a4f3-4aa6-4ebf-b121-31b4595ba1e2",
    "position": {
        "canvas": [
            {
                "x": 0.5011926058437687,
                "y": 0.5757311217808817
            },
            {
                "x": 0.501788908765653,
                "y": 0.5757311217808817
            }
        ],
        "sectional": [
            {
                "x": 0.8154639175257732,
                "y": 0.5938009787928222
            },
            {
                "x": 0.8175257731958763,
                "y": 0.5938009787928222
            }
        ],
        "sheet": [
            {
                "x": 0.5022515761032723,
                "y": 0.5745518146042851
            },
            {
                "x": 0.5028519963974782,
                "y": 0.5745518146042851
            }
        ]
    },
    "warnings": []
}

W24ThreadWhitworth¶

When dealing with Whitworth threads, the following additional attributes are available:

• Whitworth Size

Whitworth Size (Decimal)¶

Size number (for historic reasons not proportional to size)

Example Response¶

Example response for the label G1⅛

{
    "variant_id": "80ee3aea-d6d1-40e9-8cf5-f6853c312919",
    "sectional_id": "96977463-d54c-4a7b-8b51-b62c2332f7a6",
    "measures": [
        {
            "quantity": 1,
            "gender": null,
            "length": null,
            "threads": [
                {
                    "blurb": "G1.125",
                    "diameter": 28.575,
                    "unit": "MILLIMETER",
                    "thread_type": "WHITWORTH",
                    "pitch": 0.97692307692,
                    "threads_per_inch": 26,
                    "handedness": "RIGHT",
                    "multi_start": {
                        "thread_lead": null,
                        "number_of_starts": 1
                    },
                    "length": null,
                    "whitworth_size": 1.125,
                }
            ]
        }
    ]
}

W24ThreadSM¶

When dealing with SM threads, the following additional attributes are available:

• SM size

SM Size (Decimal)¶

SM size is not exact representation of the diameter.

Examples: SM05, SM1

Example Response¶

Example response for the label SM05

{
    "variant_id": "80ee3aea-d6d1-40e9-8cf5-f6853c312919",
    "sectional_id": "96977463-d54c-4a7b-8b51-b62c2332f7a6",
    "measures": [
        {
            "quantity": 1,
            "gender": null,
            "length": null,
            "threads": [
                {
                    "blurb": "0.535—40 SM",
                    "diameter": ,
                    "unit": "INCH",
                    "sm_size": 0.535,
                    "thread_type": "SM",
                    "pitch": ,
                    "threads_per_inch": 40,
                    "handedness": "RIGHT",
                    "multi_start": {
                        "thread_lead": null,
                        "number_of_starts": 1
                    },
                    "length": null,
                }
            ]
        }
    ]
}

Models¶

Threads can be extracted by requesting for Variant Measures. The data models are defined in the following models:

• Requesting the Measures: W24AskVariantMeasures

• Receiving the Measures: W24AskVariantMeasuresResponse

• Processing the Measures: W24Measure

Extracted information can be accessed from the W24Measure Model.

W24Measure¶

Measure object

Attributes:

measure_id: Unique UUID4 identifier

label: Measure Label

warnings: List of Warnings that are associated with the
    measure. See W24MeasureWarning for details.

confidence:  Werk24 calculates an internal confidence score for
    each measure. Depending on your use-case, you might want
    to consider or discard low-confidence measures. This
    value allows you to do so. The value ranges from
    0.0 to 1.0

Properties¶

• position: Refer to #/definitions/W24BaseFeaturePosition.

• measure_id (string)

• label: Refer to #/definitions/W24MeasureLabel.

• warnings (array): Default: [].

• Items: Refer to #/definitions/W24MeasureWarning.

• confidence (number): Default: 0.0.

Definitions¶

• W24BaseFeatureCoordinate (object): Coordinate point
  Attributes: x: x position normalized by the thumbnail's width
  y: y position normalized by the thumbnail's height.

• x (number)

• y (number)

• W24BaseFeaturePosition (object): Position of the Feature on the individual thumbnails normalized by the width and height of each thumbnail.
  Each features position is indicated as a list of coordinates. If the list only has two elements, you are dealing with a line. If it has four or more, you are looking at a polygon
  Attributes: page: Position of the Feature on the Page thumbnail
  sheet: Position of the Feature on the Sheet thumbnail
  sectional: Position of the Feature on the Sectional thumbnail.

• sheet (array)

  • Items: Refer to #/definitions/W24BaseFeatureCoordinate.

• canvas (array)

  • Items: Refer to #/definitions/W24BaseFeatureCoordinate.

• sectional (array)

  • Items: Refer to #/definitions/W24BaseFeatureCoordinate.

- W24SizeType (string): Enumeration class for W24 size types.
Attributes:¶

NOMINAL (str): Nominal size type. DIAMETER (str): Diameter size type. WIDTH_ACROSS_FLATS (str): Width across flats size type. Must be one of: ['NOMINAL', 'DIAMETER', 'SPHERICAL_DIAMETER', 'WIDTHS_ACROSS_FLATS', 'SQUARE'].

• W24UnitLength (string): Enum of the supported length units . Must be one of: ['METER', 'DECIMETER', 'CENTIMETER', 'MILLIMETER', 'FOOT', 'INCH', 'MICRO_INCH'].

- W24Size (object): Abstract Base Class for the Sizes.
Attributes:¶

blurb: A blurb for human consumption.
size_type: The type of size for deserialization.
nominal_size: The unit-less nominal size. The unit is attached to the parent object, which also defines the toleration.
unit: Unit of the measure if known. This should typically be inch or millimeter. In some cases it might be possible that the units are unknown.

• blurb (string)

• size_type: Refer to #/definitions/W24SizeType.

• nominal_size (number)

• unit: Refer to #/definitions/W24UnitLength.

• W24Tolerance (object): Abstract Base Class to cover the Tolerances.
  Attributes: blurb (str): String representation for human consumption
  toleration_type (W24SizeToleranceType): Toleration Type for deserialization.

• blurb (string)

• toleration_type (string)

• W24ThreadType (string): Enum for the individual thread types
  NOTE: UTS_COARSE, UTS_FINE, UTS_EXTRAFINE and UTS_SPECIAL as individual types will be deprecated. Their information individual threads_per_inch information will be stored in the corresponding variable. Must be one of: ['ISO_METRIC', 'WHITWORTH', 'UTS', 'UTS_COARSE', 'UTS_FINE', 'UTS_EXTRAFINE', 'UTS_SPECIAL'].

• W24ThreadHandedness (string): Enum describing the direction of the thread. Must be one of: ['LEFT', 'RIGHT'].

• W24ThreadMultiStart (object): Multi-Start Thread Information
  A common example of multi-start threads are the cap on a plastic water bottle. The cap will screw on quickly because a multi-start thread.
  Attributes:
  thread_lead (Decimal, optional): Thread lead for multiple starts
  number_of_starts (int): Number of intertwined threads running in parallel to one another.

• thread_lead (number)

• number_of_starts (integer): Default: 1.

• W24Thread (object): Abstract Base Class for all Threads
  Attributes: blurb (str): String representation of the thread for human consumption
  diameter (Decimal): Diameter of the thread
  diameter_preference: Not all Threads are made equal. The standardization bodies assign different preferences to the different thread diameters.
  unit (W24UnitLength): Length unit of the diameter. This allows you to differentiate between inch and millimeter (UTS or ISO METRIC). NOTE: Whitworth inch are not 2.54mm long! (for historic reasons). Use the whitworth_size if you need to have the Whitworth inches.
  thread_type: thread type to facilitate deserialization
  pitch: Pitch of the thread in mm. Normed range: 0.25 - 9mm The value will always be set - even if the pitch is give implicitly (e.g. M10c) or when the pitch is given in threads per inch. When the Pitch is ambiguous, this value be the median pitch
  threads_per_inch: Pitch and Threads per inch are interchangeable concepts. Depending on your geographic focus, the one or the other concept is more suitable. We convert ISO pitches to UTS threads per inch and vice versa, so that you do not have to handle the conversion.
  handedness: Left of right-handedness of the thread. This will be RIGHT unless explicitly described as LEFT in the drawing.
  length (Decimal, optional): Length of the Thread if specified on the label (e.g., M15x1x20). None otherwise. NOTE: If the thread length is not specified in the label, you can still obtain the information from the W24ThreadElement NOTE: If the thread label specifies both a thread length and a bore length, only the thread length will be included here. The bore length can be found in the W24MeasureElement.depth attribute.

• blurb (string)

• diameter (number)

• unit: Default: MILLIMETER.

• thread_type: Refer to #/definitions/W24ThreadType.

• pitch (number)

• threads_per_inch (number)

• handedness: Default: RIGHT.

• multi_start: Refer to #/definitions/W24ThreadMultiStart.

• length (number)

• W24UnitAngle (string): Enum of all the supported angle units
  NOTE: currently we are only supporting degrees. If you come across a drawing that uses GON, let us know, we love the concept! Must be one of: ['DEGREE'].

• W24Chamfer (object): Chamfer in degree.
  Attributes: blurb: String representation for human consumption
  angle: Chamfer angle in degrees
  unit: Angle Unit. Currently only degrees are supported.
  !!! note The chamfers can be tolerated. Future implementations will take this into account.

• blurb (string)

• angle (number)

• unit: Default: DEGREE.

• W24DepthThroughType (string): Through Type specified on ASME drawings. . Must be one of: ['THRU', 'THRU_ALL'].

• W24Depth (object): Depth object that describes the details of the depth of a drilling or thread
  Attributes: blurb: String for human consumption
  depth: Depth of the drilling or thread in the units of the parent object.

• blurb (string)

• depth (number)

• through_type: Refer to #/definitions/W24DepthThroughType.

• W24TestCriticality (string): An enumeration. Must be one of: ['CTD', 'CTF', 'CTP', 'CTQ', 'CTS'].

• W24TestDimension (object): Test Dimension attributes that can either be attached to a MeasureLabel or a GDTLabel
  Attributes: blurb: Blurb of the complete label for human consumption
  criticality: Some measures can be critical to Function, others critical to price. The TestDimensions sometimes highlight this with a shorthand (e.g., CTF)
  rate: Test rate as percentage. If a 100% inspection rate has been defined, rate will be Decimal('100'). If not defined, the rate will be None.

• blurb (string)

• criticality: Refer to #/definitions/W24TestCriticality.

• rate (number)

• W24MeasureLabel (object): Measure Label
  Attributes:
  blurb: String representation of the item for human consumption
  quantity: Quantity for spacings, e.g., (2x). Currently only the indicated measure will be detected and returned. Future implementation could detect the spacings and return individual measures for the respective spacings. When we implement this feature, we will add an attribute to the ASK, which allows you to control the behavior.
  size: Size of measure as referred to in the drawing. Sizes are always associated with units! This becomes important to remember when you are dealing with mixed-unit drawings (e.g., an adapter bolt that has an ISO thread and an UTC tapped hole). To avoid any loss of precision, we return the size in the unit that was indicated on the drawing.
  size_tolerance: Tolerance details. Default: General tolerances. By default we are referring to the general tolerances of the drawing. When you are also requesting the TitleBlock, we are attaching the applicable General Tolerances (assuming they were understood) to the measure. This will consider the nominal size of the measure. If the W24MeasureLabel describes a "Theoretically Exact Measure", i.e, the label is surrounded by a box, like: "[15]", the size_tolerance refers to a W24ToleranceTheoreticallyExact object (and is NOT None)
  unit: Length unit of the size. This information is only available when you request the TitleBlock as well; as only the title block will allow us to determine the geographic origin of the drawing.
  thread: Optional thread details. The thread details describe the complete thread description and follow the respective standards. In consequence, the thread diameter of an ISO-thread will be indicated in millimeter, while the thread diameter of an UTS thread will be in inch.
  chamfer: Optional Chamfer
  depth: Depth of the drilling or thread. Uses the same dimensions.

• blurb (string)

• quantity (integer): Default: 1.

• size: Refer to #/definitions/W24Size.

• size_tolerance: Default: {'blurb': '', 'toleration_type': 'GENERAL_TOLERANCES', 'standard': None, 'standard_class': None, 'deviation_lower': None, 'deviation_upper': None, 'tolerance_grade': None}.

• unit: Refer to #/definitions/W24UnitLength.

• thread: Refer to #/definitions/W24Thread.

• chamfer: Refer to #/definitions/W24Chamfer.

• depth: Refer to #/definitions/W24Depth.

• test_dimension: Refer to #/definitions/W24TestDimension.

• W24MeasureWarningType (string): List of all warnings that can be associated with the returned measures. Must be one of: ['UNCONVENTIONAL_TOLERANCE_ORDER', 'UNPROPORTIONAL'].

• W24MeasureWarning (object): Warnings are issued when something about the label or measure is not conforming with convention.

• warning_type: Refer to #/definitions/W24MeasureWarningType.

Requesting the Measures (includes threads)¶

from werk24 import Hook, W24AskVariantMeasures
from werk24.models.techread import W24TechreadMessage
from werk24.utils import w24_read_sync

# define a function to read a file and return it as bytes
from . import get_drawing_bytes


def recv_measures(message: W24TechreadMessage) -> None:
    """ print the Measures when we received them
    """
    if message.is_successful:
        print(message.payload_dict)
    else:
        print("Exceptions occurred: {message.exceptions}")


if __name__ == "__main__":

    # get your drawing bytes from a file or buffer
    drawing_bytes = get_drawing_bytes()

    # define what information you want to receive from the API
    # and what shall be done when the info is available.
    hooks = [Hook(ask=W24AskVariantMeasures(), function=recv_measures)]

    # submit the request to the Werk24 API
    w24_read_sync(drawing_bytes, hooks)