Hull and Outfitting

Identifying and Capturing Functions

Save PDF

Identifying and Capturing Functions

Save PDF

Last UpdatedJan 07, 2026
8 minute read

Identify Functions

This chapter describes functions to identify the nearest element in the current drawing, based on a given drawing coordinate or name (identification by name is only for views, subviews and components).

Capture Functions

This chapter describes functions to capture elements in the current drawing. The capture functions described in this chapter use the CaptureRegion2D as input parameter. This CaptureRegion2D class holds information about a 2D capture region. Region can be described by a Contour2D or Rectangle2D.

This chapter describes functions to identify arbitrary entities in the current drawing.

element_identify(Name)
The function returns a handle to the entity in the current drawing, identified by a given name. If there a multiple entities with this name, the first one encountered will be returned.
Input Parameters:
Name	string	The name of the entity
Returned value:
[0]	KcsElementHandle	Handle to the entity
Exceptions:
kcs_DrawingNotCurrent		No drawing was current
kcs_ElementNotFound		The entity was not found in the drawing
element_identify_by_padd_dbref (DbRef)
The function returns a handle to the element in the current drawing, referring to a given element in PADD.
Input Parameters:
DbRef	string	Reference to Db Element in PADD
Returned value:
[0]	KcsElementHandle	Handle to the element
Exceptions:
kcs_ValueError		Invalid parameter value
kcs_DrawingNotCurrent		No drawing was current
kcs_ElementNotFound		The element was not found in the drawing
model_identify(IdPnt, Model)
The function identifies a model, closest to a given point in the current drawing.
Input Parameters:
IdPnt	Point2D	The identification point
Model	Model	The model to identify (type & name)
Output Parameters:
Model	Model	The model identified
Returned value:
[0]	Model	The model identified
[1]	integer	Handle to the model subview
[2]	integer	Handle to the model component
Exceptions:
kcs_ValueError		Invalid parameter value
kcs_DrawingNotCurrent		No drawing was current
kcs_ModelNotFound		No model identified

subview_identify(point) subview_identify(name)
The function returns a handle to the subview on 2:nd level closest to the given point or with a given name. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
name	string	The name of the subview.
Returned value:
[0]	integer	Handle to identified subview.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_SubviewNotFound		Subview not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

element_identify_by_padd_dbref (DbRef)
The function returns a handle to the element in the current drawing, referring to a given element in PADD.
Input Parameters:
DbRef	string	Reference to Db Element in PADD
Returned value:
[0]	KcsElementHandle	Handle to the element
Exceptions:
kcs_ValueError		Invalid parameter value
kcs_DrawingNotCurrent		No drawing was current
kcs_ElementNotFound		The element was not found in the drawing

component_identify(point) component_identify(name)
The function returns a handle to the component on 3:nd level closest to the given point or with a given name. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
name	string	The name of the component.
Returned value:
[0]	integer	Handle to identified component.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_ComponentNotFound		Component not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error General error.
component_identify_by_padd_dbref (DbRef)
The function returns a handle to the component in the current drawing, referring to a given element in PADD.
Input Parameters:
DbRef	string	Reference to Db Element in PADD
Returned value:
[0]	KcsElementHandle	Handle to the component
Exceptions:
kcs_ValueError		Invalid parameter value
kcs_DrawingNotCurrent		No drawing was current
kcs_ComponentNotFound		The component was not found in the drawing
The function returns a handle to the geometry in the current drawing, referring to a given element in PADD.

dim_identify(point)
The function returns a handle to the dimension component closest to the given point. Note: Only visible layers are considered.
Input Parameters:
Point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified dimension component.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Dimension not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

note_identify(point)
The function returns a handle to the note component closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified note component.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Note not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

posno_identify(point)
The function returns a handle to the position number component closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified position number component.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Position number not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

hatch_identify(point)
The function returns a handle to the hatch component closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified hatch component.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Hatch not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

text_identify(point)
The function returns a handle to the text closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified text.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Text not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

symbol_identify(point)
The function returns a handle to the symbol closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified symbol.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Symbol not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

contour_identify(point)
The function returns a handle to the contour closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	Integer	Handle to identified contour.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Contour not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

point_identify(point)
The function returns a handle to the point closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified point.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Point not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

geometry_identify(point)
The function returns a handle to the geometry closest to the given point. Note: Only visible layers are considered.
Input Parameters:
point	Point2D	Point in drawing.
Returned value:
[0]	integer	Handle to identified geometry.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Geometry not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

geometry_identify_by_padd_dbref (DbRef)
Input Parameters:
DbRef	string	Reference to Db Element in PADD
Returned value:
[0]	KcsElementHandle	Handle to the geometry
Exceptions:
kcs_ValueError		Invalid parameter value
kcs_DrawingNotCurrent		No drawing was current
kcs_ElementNotFound		The geometry was not found in the drawing

model_capture(region)
The function returns a list of handles to models captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured models
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

dim_capture(region)
The function returns a list of handles to dimensions captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured dimensions
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

note_capture(region)
The function returns a list of handles to notes captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured notes
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

posno_capture(region)
The function returns a list of handles to position numbers captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured position numbers.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

hatch_capture(region)
The function returns a list of handles to hatches captured by given region. Note: Only visible layers are considered.
Input Parameters:
Region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured hatches
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

text_capture(region)
The function returns a list of handles to texts captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured texts
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

symbol_capture(region)
The function returns a list of handles to symbols captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured symbols
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

contour_capture(region)
The function returns a list of handles to contours captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured contours
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

point_capture(region)
The function returns a list of handles to points captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured points
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

geometry_capture(region)
The function returns a list of handles to geometries captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured geometries
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

view_capture(region)
The function returns a list of handles to views captured by given region.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of element handles.	Handles to captured views.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		The entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

subview_capture(region)
The function returns a list of handles to subviews captured by given region.
Input Parameters:
region	CaptureRegion2D.	Region in drawing.
Returned value:
[0]	List of element handles.	Handles to captured subviews.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		The entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

component_capture(region)
The function returns a list of handles to components captured by given region.
Input Parameters:
region	CaptureRegion2D.	Region in drawing.
Returned value:
[0]	List of element handles.	Handles to captured components.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		The entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

label_identify(point)
The function returns a handle to the label component closest to the given point. Note: Only visible layers are considered.
Input Parameters:
Point	Point2D	Point in drawing.
Returned value:
[0]	Integer	Handle to identified label component.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Label not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

label_capture(region)
The function returns a list of handles to labels captured by given region. Note: Only visible layers are considered.
Input Parameters:
region	CaptureRegion2D	Region in drawing.
Returned value:
[0]	List of KcsElementHandle	Handles to captured labels.
Exceptions:
kcs_ValueError		Invalid parameter value.
kcs_NotFound		Entities not found.
kcs_DrawingNotCurrent		No drawing was current.
kcs_Error		General error.

Example:

# Example: kcs_ex_draft20.py

# Example: kcs_ex_draft21.py

# Example: kcs_ex_draft22.py

Hull and Outfitting