Drawing Functions

dwg_new(DwgName, <FormName>, <DwgType>)

The function creates a new drawing and makes it the current one. The optional FormName gives the name of the drawing form.

Input Parameters:

DwgName

string

Name of drawing (maximum 25 characters)

<FormName>

string

Name of drawing form (optional)

<DwgType>

Constant or string

Drawing type. It can be defined by using:

1. drawing types constants

2. (see chapter: "Drafting Constants"):

3. for example, kcs_draft.kcsDWGTYPE_ASSEMBLY

4. logical databank names: for example, "SB_PDB"

User defined drawing databanks can be specified also by:

5. constant

6. kcs_draft.kcsDWGTYPE_USER_DEFINEDand database index

7. for example, kcs_draft.kcsDWGTYPE_USER_DEFINED + 2

8. logical databank names: for example, "SB_PDB002"

A list of all drawing databanks defined in the system can be obtained by using kcs_draft.dwg_type_list_get function.

This parameter is optional. If not given, the standard drawing databank will be used.

Returned value:

None

Exceptions:

kcs_DbError

Databank error

kcs_DrawingCurrent

A drawing is already current

kcs_DrawingExist

A drawing named DwgName already exists in the data bank

kcs_FormLocked

The drawing form is locked in the data bank.

kcs_FormNotFound

The drawing form was not found in the data bank.

kcs_NameError

Invalid name of drawing

kcs_NameOccupied

The name DwgName or FormName is used by the system.

kcs_CouldNotOpenDatabank

Not possible to open databank. Probably because of wrong user database name or id.

kcs_VolumeCurrent

A volume is already current.

dwg_open(DwgName, <DwgType>, <OpenMode>, <DwgRevision>), <EnvelopeMode>)

The function opens an existing drawing and makes it the current one. It is possible to specify a Drawing Type, an Open Mode and a Drawing Revision Name.

Input Parameters:

DwgName

string

Name of drawing

<DwgType>

constant or string

Drawing type. It can be defined by using:

9. drawing types constants

10. (see chapter: "Drafting Constants")

11. for example, kcs_draft.kcsDWGTYPE_ASSEMBLY

12. logical databank names: for example, "SB_PDB"

User defined drawing databanks can be specified also by:

13. constant

14. kcs_draft.kcsDWGTYPE_USER_DEFINED

15. and database index

16. for example, kcs_draft.kcsDWGTYPE_USER_DEFINED

17. logical databank names: for example, "SB_PDB002"

A list of all drawing databanks defined in the system can be obtained by using kcs_draft.dwg_type_list_get function.

This parameter is optional. If not given, the standard drawing databank will be used.

<OpenMode>

constant

Drawing Open Mode. It can be one of the following constants:

• kcs_draft.kcsOPENMODE_READONLY

• • kcs_draft.kcsOPENMODE_READWRITE

This parameter is optional. If it is not given, the drawing will be opened in read-write mode.

<DwgRevision>

string

Drawing Revision Name. This parameter is valid only in case of TDM usage. If an empty string is given, the latest revision of the drawing will be opened. To open the Base Revision, use the kcs_draft.kcsBASE_REVISION constant.

This parameter is optional. If not given the latest revision of drawing will be opened.

<EnvelopeMode>

constant

Drawing views envelope mode. It can be one of the following constants:

• kcs_draft.kcsENVELOPE_NONE

• kcs_draft.kcsENVELOPE_INITIAL

• kcs_draft.kcsENVELOPE_PERMANENT

This parameter is optional. If it is not given, the drawing views will be opened without envelope.

Returned value:

None

Exceptions:

kcs_Error

General error

kcs_DbError

Databank error

kcs_DrawingCurrent

A drawing is already current

kcs_DrawingLocked

The drawing is locked in the databank.

kcs_DrawingNotFound

The drawing was not found in the databank.

kcs_NameOccupied

The name is used by system.

kcs_VolumeCurrent

The volume mode is active.

Kcs_RevisionNotFound

The revision not found for given drawing.

Kcs_CouldNotOpenDatabank

Not possible to open databank. Probably because of wrong user database name or id.

dwg_pack()

The function packs the current drawing.

Arguments:

None.

Returned value:

None.

Exceptions:

kcs_DrawingNotCurrent

No drawing was current.

kcs_ArgumentError

Invalid arguments list.

dwg_purge()(<PreserveSlice>, <Preserve2dRestriction>)

The function purges the current drawing, that means, removes any empty subpictures down to subcomponent level.

Input parameters:

<PreserveSlice>

integer

Should sliced away model subviews be preserved?

0 - No, remove

1 - Yes, keep (default)

<Preserve2dRestriction>

integer

Should restricted-away model subviews be preserved?

0 - No, remove

1 - Yes, keep (default)

Returned value:

[0]

Integer

Number of empty subpictures removed.

Exceptions:

kcs_DrawingNotCurrent

kcs_Error

kcs_ArgumentError

kcs_ValueError

dwg_reference_show (show, <views>)

This function expands or collapses drawing references in current drawing.

Input Parameters:

show

true/false

Boolean value. If true then reference will be expanded otherwise collapsed.

<views>

List, tuple of ElementHandle or instance of ElementHandle.

Handles to views that should be expanded/collapsed. This parameter is optional. If not given then all reference views will be considered.

Returned value:

None.

Exceptions:

kcs_ArgumentError

Argument Error

kcs_DrawingNotCurrent

There is no current drawing.

kcs_HandleInvalid

Given handle is not a valid handle.

kcs_ValueError

Given handle is not an instance of ElementHandle.

kcs_DrawingNotFound

Reference drawing not found.

kcs_DrawingLocked

Reference drawing locked.

kcs_ReferenceDrawingInvalid

Reference drawing invalid.

kcs_DrawingEmpty

Reference drawing empty.

dwg_save()

The function saves the current drawing in the data bank. Note: An already existing version in the data bank will be overwritten!

Input Parameters:

None

Returned value:

None

Exceptions:

kcs_DbError

Data bank error

kcs_DrawingLocked

The drawing is locked in the data bank

kcs_DrawingNotCurrent

No drawing was current

kcs_ReadOnlyMode

Drawing was opened in read-only mode

dwg_save_as( NewDwgName, <NewDwgType>, <OwningRegi>)

This function saves the current drawing with a new name and drawing type.

Input Parameters:

NewDwgName

string

The new drawing name (max. 255 characters)

<NewDwgType>

constant or string

The new drawing type. It can be defined by using:

1. drawing types constants (see chapter: "Drafting Constants")

for example, kcs_draft.kcsDWGTYPE_ASSEMBLY

2. logical databank names: for example, "SB_PDB"

User defined drawing databanks can be specified also by:

1. constant kcs_draft.kcsDWGTYPE_USER_DEFINED + database index,

for example, kcs_draft.kcsDWGTYPE_USER_DEFINED + 2

2. logical databank names: for example, "SB_PDB002"

A list of all drawing databanks defined in the system can be obtained by using kcs_draft.dwg_type_list_get function.

This parameter is optional. If not given, drawing is saved with the same Drawing Type as the source Drawing.

<OwningRegi>

string

Name or DB reference (for example, "=1234/567") to owning REGI.

This parameter is optional. If given, this Regi overrides the Regi associated with the given Drawing Type.

Returned value:

None

Exceptions:

kcs_Error

General error.

kcs_DbError

Databank error.

kcs_DrawingExist

Drawing already exists in databank.

kcs_DrawingNotCurrent

No drawing was current

kcs_NameError

Invalid name of drawing

kcs_NameOccupied

The name is used by the system

kcs_ReadOnly

The drawing is Read-Only

kcs_ValueError

The drawing name is too long

kcs_ManualOwningRegiNotEnabled

Manual owning Regi not enabled

kcs_RegiNotFound

Regi not found

dwg_close()

The function closes the current drawing The drawing is not stored and will not be the current one any more.

Input Parameters:

None

Returned value:

None

Exceptions:

kcs_DrawingNotCurrent

No drawing was current

dwg_exist(DwgName, <DwgType>)

The function checks if a drawing of given type exists in the data bank.

Input Parameters:

DwgName

string

Name of drawing (maximum 25 characters)

<DwgType>

Constant or string

Drawing type. It can be defined by using:

18. drawing types constants

19. (see chapter: "Drafting Constants"):

20. for example, kcs_draft.kcsDWGTYPE_ASSEMBLY

21. logical databank names: for example, "SB_PDB"

User defined drawing databanks can be specified also by:

22. constant

23. kcs_draft.kcsDWGTYPE_USER_DEFINED

24. and database index for example,

25. kcs_draft.kcsDWGTYPE_USER_DEFINED + 2

26. logical databank names: for example, "SB_PDB002"

A list of all drawing databanks defined in the system can be obtained by using kcs_draft.dwg_type_list_get function.

This parameter is optional. If not given, any drawing type is accepted.

Returned value:

[0]

integer

0: No drawing with given name and drawing type exists.

1: A drawing with given name and drawing type exists.

Exceptions:

kcs_CouldNotOpenDatabank

Not possible to open databank. Probably because of wrong user database name or id.

dwg_delete(DwgName, <DwgType>)

The function deletes a drawing of a given type in the databank.

Input Parameters:

DwgName

string

Name of drawing (maximum 25 characters)

<DwgType>

Constant or string

Drawing type. It can be defined by using:

27. drawing types constants

28. (see chapter: "Drafting Constants"):for example, kcs_draft.kcsDWGTYPE_ASSEMBLY

29. logical databank names: for example, "SB_PDB"

User defined drawing databanks can also be specified by

30. constant

31. kcs_draft.kcsDWGTYPE_USER_DEFINEDand database indexfor example,

32. kcs_draft.kcsDWGTYPE_USER_DEFINED + 2

33. logical databank names: for example, "SB_PDB002"

Returned value:

None

Exceptions:

kcs_DbError

Data bank error

kcs_DrawingLocked

The drawing is locked in the data bank.

kcs_DrawingNotFound

The drawing is not found in the data bank.

kcs_CouldNotOpenDatabank

Not possible to open databank. Probably because of wrong user database name or id.

dwg_current()

The function checks if a drawing is current.

Input Parameters:

None

Returned value:

[0]

integer

0: No drawing is current

1: A drawing is current

Exceptions:

None

dwg_name_get()

The function returns the name of the current drawing.

Input Parameters:

None

Returned value:

[0]

string

The name

Exceptions:

kcs_DrawingNotCurrent

No drawing was current

dwg_print(options)

The function prints current drawing using selected print options.

Input Parameters:

options

PrintOptions

Python class describing print options.

Returned value:

None

Exceptions:

kcs_ValueError

Invalid parameter value.

kcs_PrinterNotFound

Selected printer not found.

kcs_PrintError

Print error: for example, wrong file name for print-to-file printing.

kcs_DrawingNotCurrent

No drawing was current.

kcs_Error

General error.

dwg_dxf_export(FileName, <ACVersion>, <Mode>, <nElemVisibility>, <nLayerVisibility>)

The function exports the current drawing to a 2D DXF file.

Input Parameters:

FileName

string

Name of file to be created. The file must not exist before. If no path is given, the file is created in current directory. If no extension is given, the default extension .dxf will be used.

<ACVersion>

integer

Version of AutoCAD in which exported file will be open. It can be one of the following values:

12 - for R12

13 - for R13

14 - for R14

15 - for R15 (AutoCAD 2000) (default)

18 - for R18 (AutoCAD 2004)

This parameter is optional.

<Mode>

integer

Type of dxf file:

0   ext dxf file (default)

1 - binary dxf file

This parameter is optional.

<nElemVisibility>

integer

Type of exports hidden elements:

0 - hidden elements are invisible in exported file (default)

1 - hidden elements are visible in exported file

<nLayerVisibility>

integer

Type of exports hidden layers:

0 - hidden layers are invisible in exported file (default)

1 - hidden layers are visible in exported file

Returned value:

None.

Exceptions:

kcs_ArgumentError

Invalid parameter type.

kcs_DrawingNotCurrent

No drawing was current.

kcs_AlreadyExist

Destination file already exists.

kcs_ValueError

Version is not valid.

kcs_Error

Internal error. Drawing can not be exported.

dwg_dxf_import(FileName, DrawingName, <MapFileName>)

The function imports the drawing from a 2D DXF file. No drawing must be current before.

Input Parameters:

FileName

string

Name of file to be opened. If no extension is given, the default extension .dxf will be used.

<MapFileName>

string

Name of file with import map definition. This parameter is optionally. Default import map is defined in dxfimport.def file located in directory described by SBGD_DEF.

The format of this file is as follows:

It is divided in three sections:

One for mapping layers, one for mapping linetypes and one for mapping fonts. These sections have specified headers ([LAYERS], [LTYPES], [FONTS]) followed by pairs of DXF objects and corresponding Drafting objects to be used, every value in a new line. The example here shows how such mapping file could look like.

[LAYERS]
dxflayer1
34
dxflyer2
55
[LTYPES]
BYLAYER
SYSTEM32

DrawingName

string

Name for new drawing that will be created.

Returned value:

None.

Exceptions:

kcs_ArgumentError

Invalid parameter type.

kcs_DrawingIsCurrent

There is current drawing.

kcs_DoesNotExist

Source file doesn’t exist.

kcs_ValueError

For some reasons file can not be opened or illegal drawing name.

kcs_NameOccupied

Drawing name is already in use.

kcs_Error

Internal error. Drawing can not be imported.

Example

#Example:kcs_ex_draft32.py

dwg_dxf_2d3d_export(FileName, ViewSubviewsList, Paper, Margins <DetailLevel>, <ACVersion>, <Mode>, <nElemVisibility>, <nLayerVisibility>)

The function exports selected views/subviews to 2d3d dxf file. Model parts are exported to ModelSpace block as 3D entities. Non-model parts are exported to PaperSpace block as 2D entities.

Input Parameters:

FileName

string

Name of file to be created. The file must not exist before. If no path is given, the file is created in current directory. If no extension is given, the default extension .dxf will be used.

ViewSubviewsList

list of Element Handle

List of views and/or subviews handles. Specified views/subviews must be model views/subviews.

Paper

Vector2D

Paper size

Margins

Vector2D

Margins size

<DetailLevel>

integer

Level of dxf file detail. It can be one of the following:

1 - Low detail

2 - Medium detail

3 - High detail (default)

4 - Extra detail

This parameter is optional.

<ACVersion>

integer

Version of AutoCAD in which exported file will be open. It can be one of the following values:

12 - for R12

13 - for R13

14 - for R14

15 - for R15 (AutoCAD 2000) (default)

18 - for R18 (AutoCAD 2004)

This parameter is optional.

<Mode>

integer

Type of dxf file:

0 - text dxf file (default)

1 - binary dxf file

This parameter is optional.

<nElemVisibility>

integer

Type of exports hidden elements:

0 - hidden elements are invisible in exported file (default)

1 - hidden elements are visible in exported file

<nLayerVisibility>

integer

Type of exports hidden layers:

0 - hidden layers are invisible in exported file (default)

1 - hidden layers are visible in exported file

Returned value:

None.

Exceptions:

kcs_ArgumentError

Invalid parameter type.

kcs_DrawingNotCurrent

No drawing was current.

kcs_AlreadyExist

Destination file already exists.

kcs_HandleInvalid

List of views/subviews is empty or there are handles for not model views/subviews.

kcs_ValueError

This exception is generated if:

• detail level or version is not valid

• for some reasons output file can't be opened. For example file on read only drive.

kcs_Error

Internal error. Drawing cannot be exported.

dwg_dxf_3d_export(FileName, ViewSubviewsList, <DetailLevel>, <ACVersion>, <Mode>)

The function exports all models in the given views and subviews to a 3D DXF Facet format.

Input Parameters:

FileName

string

Name of file to be created. The file must not exist before. If no path is given, the file is created in current directory. If no extension is given, the default extension .dxf will be used.

ViewSubviewsList

list of

List of views and/or subviews handles. Specified

Element Handle

views/subviews must be model views/subviews.

<DetailLevel>

integer

Level of dxf file detail. It can be one of the following:

1 - Low detail

2 - Medium detail

3 - High detail (default)l

4 - Extra detail

This parameter is optional.

<ACVersion>

integer

Version of AutoCAD in which exported file will be open. It can be one of the following values:

12 - for R12

13 - for R1314 - for R14

15 - for R15 (AutoCAD 2000) (default)

18 - for R18 (AutoCAD 2004)

This parameter is optional.

<Mode>

integer

Type of dxf file:

0 - text dxf file (default

1 - binary dxf file

This parameter is optional.

Returned value:

None.

Exceptions:

kcs_ArgumentError

Invalid parameter type.

kcs_DrawingNotCurrent

No drawing was current.

kcs_AlreadyExist

Destination file already exists.

kcs_HandleInvalid

List of views/subviews is empty or there are handles for not model views/subviews.

kcs_ValueError

This exception is generated if:

• detail level or version is not valid

• for some reasons output file can’t be opened. For example file on read only drive.

kcs_Error

Internal error. Drawing can not be exported.

dwg_wmf_export(FileName)

The function exports the current drawing to a metafile.

Input Parameters:

FileName

string

Name of file to be created. The file must not exist before. If no path is given, the file is created in current directory. If no extension is given, the default extension .wmf will be used.

Returned value:

None.

Exceptions:

kcs_ArgumentError

Invalid parameter type.

kcs_DrawingNotCurrent

No drawing was current.

kcs_AlreadyExist

Destination file already exists.

kcs_ValueError

For some reasons file can not be opened. For example file on read only drive.

kcs_Error

Internal error. Drawing can not be exported.

dwg_preview_bmp_export(FileName,DwgType,DwgName)

The function exports the preview of the given drawing to a bitmap file. Please note that a preview of this drawing must exist in the preview image database.

Input Parameters:

FileName

string

Name of file to be created. If no path is given, the file is created in current directory.

DwgType

integer

The drawing type code for the drawing.

DwgName

string

Name of the drawing to create a bitmap file from.

Returned value:

None.

Exceptions:

kcs_ArgumentError

Invalid parameter.

kcs_FileError

The file could not be created.

kcs_PreviewError

The preview object could not be found in the preview image database.

Example:

#kcs_ex_draft43.py

form_name_get()

The function returns form name of current drawing.

Input Parameters:

None

Returned value:

[0]

string

Name of drawing form

Exceptions:

kcs_ArgumentError

Invalid parameter type.

kcs_DrawingNotCurrent

No drawing was current.

kcs_NotFound

Drawing has no form.

kcs_Error

General error

dwg_type_list_get()

The function returns all drawing types registered in the system as a Python dictionary.

Input Parameters:

None

Returned value:

[0]

dictionary

The dictionary contains drawing types as keys and pairs: description and logical databank name as values. Example:

kcsDWGTYPE_GEN : ('General drawing', 'SB_PDB')

You can find all registered types using keys() function of the returned dictionary.

User defined drawing types

Any of user defined drawing types are equal to:

kcsDWGTYPE_USER_DEFINED + database index

where index starts from 1. It means that each type which has a value higher than kcsDWGTYPE_USER_DEFINED is a user defined drawing type.

Exceptions:

kcs_Error

General error

Example:

#kcs_ex_draft01.py

dwg_validate(OutOfDate, NotFound)

The function validates the current drawing and returns two lists of KcsModel.Model instances. The first list contains model objects that have been updated on the databank after this drawing was saved. List two contains model objects in the drawing that cannot be found on the databank. Only one instance of the object is returned and always as un-reflected.

Input parameters:

OutOfDate

List

NotFound

List

Returned value:

[0]

OutOfDate

List of KcsModel objects

[1]

NotFound

List of KcsModel objects

Exceptions:

kcs_DrawingNotCurrent

kcs_Error

dwg_layers_is_shown ()

The function tests if application display mode is show layers. If show layers mode is active the function returns true otherwise false.

Input Parameters:

None

Returned value:

[0]

integer

0: Show layers mode is not active

1: Show layers mode is active

Exceptions:

kcs_DrawingNotCurrent

No drawing is current

dwg_layers_is_hidden()

The function tests if application display mode is hide layers. If hide layers mode is active the function returns true otherwise false.

Input Parameters:

None

Returned value:

[0]

integer

0: Hide layers mode is not active

1: Hide layers mode is active

Exceptions:

kcs_DrawingNotCurrent

No drawing is current

dwg_layers_shown_get ()

The function returns list of layers that are displayed when application mode is show layers.

Input Parameters:

None

Returned value:

[0]

list

List of KcsLayer objects

Exceptions:

kcs_DrawingNotCurrentkcs_LayersDisplayModeInvalid

No drawing is current. Application is not in show layers mode

dwg_layers_hidden_get ()

The function returns list of layers that are hidden when application mode is hide layers.

Input Parameters:

None

Returned value:

[0]

list

List of KcsLayer objects

Exceptions:

kcs_DrawingNotCurrentkcs_LayersDisplayModeInvalid

No drawing is current. Application is not in hide layers mode

Example:

kcs_ex_draft26.py

Subpicture_transfer (elementHandle, targetDrawingName, positioningCode)

The function copies a view/subview/component in the current drawing to another drawing in the database. The subpicture to copy is given by the element handle. The target drawing is given by name and must exist in the data base. The positioning code denotes the wanted position in the drawing form of the target drawing and is given as an integer value (optional). If not given, or no drawing form exists in the target drawing, the default position is "Same as in source drawing".

Input Parameters:

elementHandle

KcsElementHandle

Handle to a viev, subview or

component

targetDrawingName

string

Name of target drawing

(of any drawing type)

positioningCode

int

Code denoting the wanted position in the drawing form of the target drawing (Optional).

If not given, or no drawing form exists, the default position is "same as in source drawing:"

= 1 Same as in source drawing

= 2 Middle

= 3 East

= 4 NorthEast

= 5 North

= 6 NorthWest

= 7 West

= 8 SouthWest

= 9 Souyth

= 10 SouthEast

Returned value:

None

Exceptions:

kcs_ArgumentError

Invalid parameters

kcs_DrawingNotCurrent

No drawing was current

kcs_HandleInvalid

Not a valid view/subview/component handle

kcs_NameUsedInWorkspace

Name of target drawing is occupied in workspace

kcs_DrawingLocked

Target drawing is locked

kcs_ DrawingE3DAccessOnly

Target drawing can only be accessed by E3D software

kcs_DrawingNotFound

Target drawing not found in database

kcs_AccessDenied

Access of target drawing denied

kcs_Error

General unspecified error

Form_insert ( FormName)

The function inserts/exchanges a Drawing Form or Backing Sheet in the current drawing.

If a drawing form already exists in the drawing, it will be replaced.

Input Parameters:

FormName

string

Name of the drawing form/backing sheet

Returned value:

None

Exceptions:

kcs_ArgumentError

Invalid parameters

kcs_DrawingNotCurrent

No drawing was current

kcs_NameUsedInWorkspace

Name of Drawing form is occupied in workspace

kcs_FormNotFound

Drawing form not found in database

kcs_AccessDenied

Access of Drawing form denied

kcs_Error

General unspecified error

Example:

These are examples on how to use the drawing functions.

# Example: kcs_ex_draft1.py

# Example: kcs_ex_draft27.py

# Example: kcs_ex_draft30.py