Surface Roughnesses¶

The surface roughness symbol defines the smoothness of the referred surface. Most modern standards use a variation of the square root symbol to specify it. To simplify

Supported Roughness Standards¶

While a whole range of different standards exist, the standards that are most frequently used today are ISO1302 and ASME Y14.36

N-Grades¶

Surface Roughnesses can be complex and the similarity of the symbols across different standards add to the confusion. None the less, most of our partners will likely care about one core feature - the N-Grade. It maps the specified roughness to a categorical value between "01" (corresponds to -1) to "12". This simplification ensures that you do not have to worry about the different standards, the differences between average profile height, maximum profile height, etc. WERK24 calculates this values whenever possible.

When you do use the N-Grade feature, be aware of two things:

1. Surface Roughnesses can specify Upper and Lower limits, as well as Averages for the surface roughness. When you use WERK24 to inform your price calculation, you will likely care about the Upper and Average specifications, and attribute less value to the Lower limit.

2. Surface Roughnesses can specify requirements for the Profile (P), Roughness (R), and Waviness (W) of the surface. The Profile corresponds to the actual measurement when scanning the surface. Mathematical filters are then applied to obtain the Roughness and the Waviness. Here, Roughness describes the smaller irregularities, while the Waviness describe larger, regular changes of the surface. The N-Grades are defined for the Roughness - while is what most engineering drawings specify (e.g., Ra3.2). This allows us to convert Roughness values directly into N-grades. The Profile (P) also contains information about the Roughness (but also about the Waviness). The conversion of Profiles to N-grades however relies on empirical formulas. As the empirical experience of companies vary, Profile-based N-grade classifications are less accurate, and sometimes a supplier might classify the same Profile one N-grade higher or lower. The Waviness (W) does not contain any roughness information, and it thus has no N-grade.

Werk24 converts surface roughness parameters to N-Grades as per following conversions. Please reach out to us if you find any discrepancies in the conversions.

Models¶

The data models are defined in the following models:

• Requesting the Roughnesses: W24AskVariantRoughnesses
• Receiving the Roughnesses: W24AskVariantRoughnessesResponse
• Processing the Roughness: W24Roughness

Extracted information can be accessed from the W24Roughness Model.

W24Roughness¶

Roughness object

Attributes: roughness_id: Unique UUID4 identifier

label: RoughnessLabel

Properties¶

• position: Refer to #/definitions/W24BaseFeaturePosition.

• roughness_id (string)

• label: Refer to #/definitions/W24RoughnessLabel.

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.

• W24RoughnessStandard (string): Most standards that define the surface roughness use very similar symbols. However, the position of the fields varies.
  The standards listed here are understood and supported by the API.
  NOTE: the ISO 1302 standard exists in four different versions, these releases substantially modified the position and structure of the roughness symbols.
  NOTE: this list is not exhaustive, many countries have specified their own standards over the years. Do not hesitate to reach out if you wish us to implement another standard. Must be one of: ['ISO 1302:1978', 'ISO 1302:1992', 'ISO 1302:2002', 'ISO 21920-1:2021', 'ASME Y14.36-1978', 'ASME Y14.36M-1996', 'ASME Y14.36-2018'].

• W24RoughnessMaterialRemovalType (string): Most standard allow the designer to specify whether material removal is required or prohibited.
  By default both options are allowed. Must be one of: ['UNSPECIFIED', 'PROHIBITED', 'REQUIRED'].

• W24RoughnessDirectionOfLay (string): The lay of the roughness limits the manufacturing process and is sometimes required for the application. Must be one of: ['=', '⟂', 'X', 'M', 'C', 'R', 'P'].

• W24ManufacturingMethod (object): Manufacturing method specified on the drawing. Currently only the blurb is available.
  Attributes: blurb: Manufacturing method as specified on the drawing.

• blurb (string)

• W24RoughnessConditionType (string): Roughnesses can specify, the upper limit, the lower limit and the average. Must be one of: ['U', 'L', 'A'].

• W24RoughnessFilterType (string): When measuring the roughness, different filter types will result in different results. To reduce this source of ambiguity, the designer can specify the filter to be used.
  NOTE: this list is not exhaustive. If you need us to support another filter method, please reach out. Must be one of: ['G', 'RG', 'S', '"2RC"'].

• W24RoughnessParameter (string): Roughness Parameter that is specified.
  NOTE: this list is not exhaustive, but covers the most frequently used parameters. Must be one of: ['AA', 'CLA', 'PVA', 'RMS', 'Pa', 'PC', 'Pku', 'Pp', 'Pq', 'Psk', 'Pt', 'Pv', 'Py', 'Pz', 'Ra(DIN)', 'Ra(ISO)', 'Rc', 'Rku', 'Rp', 'Rq', 'Rsk', 'Rt', 'Rv', 'Ry', 'Rz', 'Wa', 'Wc', 'Wku', 'Wp', 'Wq', 'Wsk', 'Wt', 'Wv', 'Wy', 'Wz', 'N'].

• W24RoughnessEvaluationLengthType (string): An enumeration. Must be one of: ['LENGTH', 'LAMBDA_C_MULTIPLE'].

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

• W24RoughnessEvaluationLength (object): For sophisticated application, the sample needs to be taken over a longer distances. This is specified the either the sampling length in millimeter (ISO 3012:1974, ISO 3012:1978, ISO 3012:1992) or as multiple of the main lambda (ISO 3012:2002 and ISO 3012:2021).
  
  Attributes: evaluation_length_type: Sampling length type that is specified by the applicable standard
  length: evaluation length in the specified units.
  length_unit: Millimeter for both the ISO and ASME standards
  lambda_c_multiple: multiple of the main cutoff lambda_c.

• evaluation_length_type: Refer to #/definitions/W24RoughnessEvaluationLengthType.

• length (number)

• length_unit: Refer to #/definitions/W24UnitLength.

• lambda_c_multiple (number)

• W24RoughnessAcceptanceCriterion (string): The designer can specify whether to apply the 16%-rule, the maximum- or medium- rule when deciding whether a surface complies with the specifications. Must be one of: ['16%', 'max', 'mean'].

• W24RoughnessGrade (object): ISO Roughness Grade
  Attributes: blurb: String representation for human consumption
  grade: Roughness Grade in the range N01 to N12. Valid values are N01, N0, N1, N2, N3, N4, N5, N6, N7, N8, N9, N10, N11, N12, N13, N14.

• blurb (string)

• grade (string)

• W24RoughnessCondition (object): Roughness Label
  Attributes: blurb: String representation of the Roughness for human consumption.
  condition_type: Roughness Side that is specified (upper or lower). We automatically determine this value depending on the standard and the position of the parameter
  filter_type: Filter Type to use when measuring the surface. When not specified on the drawing, we set the default value according to the applicable standard.
  lambda_s: Filter bandwidth microroughness cutoff lambda_s. When not specified, we determine the default value based on the standard and the value_limit.
  lambda_c: Filter bandwidth main cutoff lambda_c. When not specified, we determine the default value based on the standard and the value_limit.
  parameter: Parameter to be measured
  
  characteristic: Method of converting the 2D-measurement into a single number
  evaluation_length: For sophisticated application, the roughness needs to be evaluated over a longer distances. This is specified the either the sampling length in millimeter (ISO 3012:1974, ISO 3012:1978, ISO 3012:1992) or as multiple of the main lambda (ISO 3012:2002 and ISO 3012:2021).
  acceptance_criterion: Designers can specify what rule to apply when deciding whether a measured tolerance complies with the requirements
  value_limit: Specification limit
  roughness_grade: ISO roughness grade that the roughness specifications correspond to. IMPORTANT: this allows you to deal with all the standards in a simple way.

• blurb (string)

• condition_type: Refer to #/definitions/W24RoughnessConditionType.

• filter_type: Refer to #/definitions/W24RoughnessFilterType.

• lambda_s (number)

• lambda_c (number)

• parameter: Refer to #/definitions/W24RoughnessParameter.

• evaluation_length: Refer to #/definitions/W24RoughnessEvaluationLength.

• acceptance_criterion: Refer to #/definitions/W24RoughnessAcceptanceCriterion.

• value (number)

• roughness_grade: Refer to #/definitions/W24RoughnessGrade.

• W24UnitSystem (string): Unit System that is used for a certain feature . Must be one of: ['METRIC', 'IMPERIAL'].

• W24RoughnessWaviness (object): Roughness Waviness as defined in the ASME-Y14-36
  Attributes: waviness_height: Waviness height in inch waviness_width: Waviness width in inch.

• waviness_height (number)

• waviness_width (number)

• W24RoughnessLabel (object): Roughness Label
  Attributes: blurb: String for human consumption
  blurb_html: HTML for human consumption. The complex structure of the symbol makes this necessary.
  standard : Standard in which the Roughness Symbol is written NOTE: there are multiple standards that are in use
  machining_allowance: Machining Allowance in millimeter of micro-inch. See the unit attribute.
  material_removal_type: The MaterialRemovalType specifies whether material must / must not be removed.
  applies_all_around: Boolean value that specifies whether the roughness applies to all surfaces around
  direction_of_lay: The lay of the roughness limits the manufacturing process and is sometimes required for the application.
  manufacturing_method: Method by which to achieve the roughness
  conditions: Roughness conditions
  unit_system: Unit system that is used for the roughness. We are not using the explicit units as the different attributes have different units (e.g, micro and nano meters)
  waviness: Waviness defined in ASME standards.

• blurb (string)

• blurb_html (string)

• standard: Refer to #/definitions/W24RoughnessStandard.

• machining_allowance (number)

• material_removal_type: Refer to #/definitions/W24RoughnessMaterialRemovalType.

• applies_all_around (boolean)

• direction_of_lay: Refer to #/definitions/W24RoughnessDirectionOfLay.

• manufacturing_method: Refer to #/definitions/W24ManufacturingMethod.

• conditions (array)

  • Items: Refer to #/definitions/W24RoughnessCondition.

• unit_system: Refer to #/definitions/W24UnitSystem.

• waviness: Refer to #/definitions/W24RoughnessWaviness.

Requesting the Roughnesses¶

from werk24 import Hook, W24AskVariantRoughnesses
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 Roughnesses 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=W24AskVariantRoughnesses(), function=recv_measures)]

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

Example Response¶

{
    "variant_id": "3a9e2a06-0839-4f7c-b7a6-995dea97b28b",
    "sectional_id": "d1c80a29-1998-4ae8-80b0-173464929355",
    "roughnesses": [
        {
            "position": null,
            "roughness_id": "1a190f2f-c1ae-4c67-9f13-f530908af450",
            "label": {
                "blurb": "\u25bd\u221aURa(DIN)  12.5",
                "blurb_html": "",
                "standard": "ISO 1302:2002",
                "machining_allowance": null,
                "material_removal_type": "REQUIRED",
                "applies_all_around": false,
                "direction_of_lay": null,
                "manufacturing_method": {
                    "blurb": "None"
                },
                "conditions": [
                    {
                        "blurb": "URa(DIN)  12.5",
                        "condition_type": "U",
                        "filter_type": "G",
                        "lambda_s": 0.03,
                        "lambda_c": 0.8,
                        "parameter": "Ra(DIN)",
                        "evaluation_length": {
                            "evaluation_length_type": "LAMBDA_C_MULTIPLE",
                            "length": 4.0,
                            "length_unit": "MILLIMETER",
                            "lambda_c_multiple": 5
                        },
                        "acceptance_criterion": "16%",
                        "value": 12.5,
                        "roughness_grade": {
                            "blurb": "N7",
                            "grade": "7"
                        }
                    }
                ],
                "unit_system": "METRIC",
                "waviness": null
            }
        },
        {
            "position": null,
            "roughness_id": "26b47620-74ff-4401-b722-58e91077359b",
            "label": {
                "blurb": "\u25bd\u221aURa(DIN)  3.2",
                "blurb_html": "",
                "standard": "ISO 1302:2002",
                "machining_allowance": null,
                "material_removal_type": "REQUIRED",
                "applies_all_around": false,
                "direction_of_lay": null,
                "manufacturing_method": {
                    "blurb": "None"
                },
                "conditions": [
                    {
                        "blurb": "URa(DIN)  3.2",
                        "condition_type": "U",
                        "filter_type": "G",
                        "lambda_s": 0.03,
                        "lambda_c": 0.8,
                        "parameter": "Ra(DIN)",
                        "evaluation_length": {
                            "evaluation_length_type": "LAMBDA_C_MULTIPLE",
                            "length": 4.0,
                            "length_unit": "MILLIMETER",
                            "lambda_c_multiple": 5
                        },
                        "acceptance_criterion": "16%",
                        "value": 3.2,
                        "roughness_grade": {
                            "blurb": "N7",
                            "grade": "7"
                        }
                    }
                ],
                "unit_system": "METRIC",
                "waviness": null
            }
        }
    ]
}