VrOne/Python Programming

A VrOne workspace is created when a VrOne vector file is opened. There may be up to 256 files opened at one time in VrOne. The Workspace Class manages VrOne file operations and may be queried for workspace status. When a VrOne file is opened and becomes a VrOne Workspace some entity parameters such as Layer and Minimum Bounding Rectangle are stored in memory. This enables fast searching without accessing the disk drive as the FindLayer12.py example below shows. The user of this class should understand the VrOne Data Structure.

NOTE: The workspace numbers start at one in VrOne but start at zero when programming in VrOne/Python.

The FindLine12.py example searches all open workspaces for entities in layer 12. The workspace object is queried for layer number and the disk is never accessed. This is much faster than loading each entity from disk and querying the entity object (PyVrLine, PyVrSym or PyVrText) for the layer number.

# Count lines, symbols and text in layer 12 in all open workspaces

# Filename: FindLayer12.py

Ws = PyVrWs () # VrOne workspace manager

WsNum = 0 # Workspace numbers start at 0

LineCount = 0

SymCount = 0

TextCount = 0

for WsNum in range (0, Ws.GetWsCount()):

for LineNum in range (0, Ws.GetLineCount(WsNum)):

if Ws.GetLineLayer (WsNum, LineNum) == 12:

LineCount += 1

for SymNum in range (0, Ws.GetSymCount (WsNum)):

if Ws.GetSymLayer (WsNum, SymNum) == 12:

SymCount += 1

for TextNum in range (0, Ws.GetTextCount (WsNum)):

if Ws.GetTextLayer (WsNum, TextNum) == 12:

TextCount += 1

print "There are", Ws.GetWsCount(), "workspaces open"

print "There are", LineCount, "lines in layer 12"

print "There are", SymCount, "symbols in layer 12"

print "There are", TextCount, "text labels in layer 12"

Member Function Documentation

Aws ()

Returns the VrOne active workspace, which is the workspace that new data will be placed in VrOne. NOTE: The workspace numbers start at one in VrOne but start at zero when programming in VrOne/Python.

Returns Active workspace (0-255)

Example WsNum = Ws.Aws()

SetAws (WsNum)

Sets the active workspace. NOTE: The workspace numbers start at one in VrOne but start at zero when programming in VrOne/Python. There must be a VrOne file open in the workspace to make it active. If the workspace number is out of range then nothing is done.

WsNum Active workspace (0-255)

Example Ws.SetAws (1)

Open (FileName, Create, Units, Scale)

Opens a new workspace.

FileName	File name to open.
Create	1 - Create the file if it doesn't exist. (default=1) 2 - Do not create the file if it doesn't exist.
Units	Units to create file with 0 - UsFoot (default) 1 - Meter 2 - IntlFoot
Scale	Scale to create file with (1"=n) (default=100)
WsNum	Return workspace number (optional)
Returns	Stat, WsNum, ErrorStrg
	Stat	0 - OK, file existed and was opened. 1 - File did not exist and was created. 2 - File size check failed. (Fixed) 3 - Encountered non header record. (Fixed) -1 - Could not open file. -2 - File did not exist and it could not be created. -3 - Could not get file size. (system error) -4 - File damaged and could not be repaired. Is this a VrOne file? -5 - Maximum number of workspaces reached.
	WsNum	Number assigned to new workspace
	ErrorStrg	If there was an error, this is a description of the error. May be useful to show user.

Example

(Stat, RetWs, RetErrorStrg) = Ws.Open ("MyFile.vr", 0, 600)

Close (WsNum)

Closes the workspace specified.

WsNum

Workspace number to close..

Returns

Stat, WsNum, ErrorStrg

Stat

0 = OK

-22 = Workspace number out of range.

Example

Stat = Ws.Close (0)

CloseByName (FileName)

Closes the workspace described by filename.

FileName

File name that was used to open the workspace The one that was returned from GetFileName.

If FileName is not open then nothing is done.

Returns

Stat, WsNum, ErrorStrg

Stat

0 = OK

-22 = Workspace number out of range.

Example

Stat = Ws.Close (0)

IsOpen (FileName)

Checks if workspace is open by file name.

FileName	File name to check. Must be the same file name that was used to open the workspace (with full path).
Returns	0=Not Open, 1=Open

Example

(Stat, RetWs, RetErrorStrg) = Ws.Open ("f:/jobs/myfile.vr", 0, 600)

if (Stat == 0):

Stat = Ws.IsOpen ("f:/jobs/myfile.vr")

Pack (WsNum)

Packs workspaces.

WsNum	Wokspace to pack (-1 = Pack all open workspaces)
Returns	void

Example

Ws.Pack (0)

Backup (WsNum)

Backs up the file of the workspace specified. Copies workspace file to a file with a .vrb extension.

WsNum	Workspace to backup.
Returns	0=Ok, -1=Error

Example

Stat = Ws.Backup (0)

FindLine (SeaWs, Win, SeaX, SeaY, SeaZ, SeaRad, SeaMode, RetMode)

Finds the closest line to the point sent.

SeaWs	Workspace to search (-1=Search all open workspaces)
Win	Window number for search (-1=All)
SeaX, SeaY, SeaZ	Search point
SeaMode	Search mode 0 - Point search. Find the closest line point. 1 - Line search. Find the closest line then the closest point on that line.
RetMode	Return mode 0 - Return line point. 1 - Return intersection of search point and line. 2 - Return closest end point
Returns	Stat, RetWs, RetLineNum, RetPntNum, RetX, RetY, RetZ, RetDist
	Stat	0 = OK, -1 = Search point was not within any existing MBR
	RetWs	Return workspace.
	RetLineNum	Return line number.
	RetPntNum	Return point number.
	RetX	Return X coordinate.
	RetY	Return Y coordinate.
	RetZ	Return Z coordinate.
	RetDist	Return distance from search point to line found.

Example

(ret, retws, retlinenum, retpntnum, retx, rety, retz, retdist) = Ws.FindLine (aws, -1, x, y, z, 10.0, 1, 0)

FindSym (SeaWs, Win, SeaX, SeaY, SeaZ, SeaRad)

Finds the closest symbol to the point sent.

SeaWs	Workspace to search (-1=Search all open workspaces)
Win	Window number for search (-1=All)
SeaX, SeaY, SeaZ	Search point
Returns	Stat, RetWs, RetSymNum, RetX, RetY, RetZ
	Stat	0 = OK, -1 = Search point was not within any existing MBR
	RetWs	Return workspace.
	RetSymNum	Return symbol number.
	RetX	Return X coordinate.
	RetY	Return Y coordinate.
	RetZ	Return Z coordinate.

Example

(ret, retws, retsymnum, retx, rety, retz) = Ws.FindSym (aws, -1, x, y, z, 10.0)

FindText (SeaWs, Win, SeaX, SeaY, SeaZ, SeaRad)

Finds the closest text label to the point sent.

SeaWs	Workspace to search (-1=Search all open workspaces)
Win	Window number for search (-1=All)
SeaX, SeaY, SeaZ	Search point
Returns	Stat, RetWs, RetTextNum, RetX, RetY, RetZ
	Stat	0 = OK, -1 = Search point was not within any existing MBR
	RetWs	Return workspace.
	RetTextNum	Return symbol number.
	RetX	Return X coordinate.
	RetY	Return Y coordinate.
	RetZ	Return Z coordinate.

Example

(ret, retws, retsymnum, retx, rety, retz) = Ws.FindSym (aws, -1, x, y, z, 10.0)

FindClosestEnt (SeaWs, Win, SeaType, SeaX, SeaY, SeaZ, SeaRad, SeaMode, RetMode)

Finds the closest entity to the point sent..

SeaWs	Workspace to search (-1=Search all open workspaces)
Win	Window number for search (-1=All)
SeaType	Entity types to search for SEA_LINE\|SEA_SYM\|SEA_TEXT (may be or'ed)
SeaX, SeaY, SeaZ	Search point
SeaMode	Search mode 0 - Point search. Find the closest line point. 1 - Line search. Find the closest line then the closest point on that line.
RetMode	Return mode 0 - Return line point. 1 - Return intersection of search point and line. 2 - Return closest end point
Returns	Stat, RetWs, RetEntNum, RetEntType, RetPntNum, RetX, RetY, RetZ, RetDist
	Stat	0 = OK, -1 = Search point was not within any existing MBR
	RetWs	Return workspace.
	RetEntNum	Return entity number.
	RetEntType	Return entity type 1=Line 3=Symbol 4=Text
	RetPntNum	Return point number (if Line)
	RetX	Return X coordinate.
	RetY	Return Y coordinate.
	RetZ	Return Z coordinate.
	RetDist	Return distance from search point to line found (if Line).

Example

(ret, retws, rettype, retentnum, retpntnum, retx, rety, retz, retdist) = Ws.FindClosestEnt (aws, -1, SEA_LINE|SEA_TEXT|SEA_SYM, x, y, z, 10.0, 1, 0)

IdEnt (SeaWs, SeaLines, SeaSymbols, SeaText)

Displays menu keys dialog and allows user to select any entity.

SeaWs	Workspace to search (-1=Search all open workspaces)
SeaLines	Search for lines (0=No, 1=Yes)
SeaSymbols	Search for symbols (0=No, 1=Yes)
SeaText	Search for text (0=No, 1=Yes)
Returns	Stat, RetWs, RetEntNum, RetEntType, RetPntNum, RetX, RetY, RetZ, RetDist
	RetWs	Return workspace.
	RetEntNum	Return entity number.
	RetEntType	Return entity type 1=Line 3=Symbol 4=Text
	RetPntNum	Return point number (if Line)
	RetX	Return X coordinate.
	RetY	Return Y coordinate.
	RetZ	Return Z coordinate.

Example

(retWs, retEntNum, retEntType, retPntNum, retLockX, retLockY, retLockZ) = Ws.IdEnt ()

GetWsCount ()

Returns the number of open workspaces.

Returns Number of open workspaces (0-255)

Example WsCount = Ws.GetWsCount(0)

GetTargetScale (WsNum)

Returns the target scale of a workspace in ratio form.

WsNum Workspace number (0-255)

Returns Target scale in ratio form (1:n)

Example TargetScale = Ws.GetTargetScale(0)

GetTargetScaleIn (WsNum)

Returns the target scale of a workspace in inches form.

WsNum Workspace number (0-255)

Returns Target scale in inch form (1”=n)

Example TargetScale = Ws.GetTargetScaleIn(0)

GetUnits (WsNum)

Returns the units of a workspace.

WsNum Workspace number (0-255)

Returns Units (0=UsFoot 1=Meter 2=International Foot)

Example Units = Ws.GetUnits (0)

GetFileName (WsNum)

Returns the file name of a workspace.

WsNum Workspace number (0-255)

Returns File name of workspace.

Example FileName = Ws.GetFileName (0)

GetMinMax (WsNum)

Returns the minimum and maximum coordinates for a workspace.

WsNum Workspace number (0-255)

Returns Minimum and maximum coordinate value of workspace

Example (MinX, MinY, MinZ, MaxX, MaxY, MaxZ) = Ws.GetMinMax (0)

GetLineCount (WsNum)

Returns the number of lines in a workspace. NOTE: Deleted entities are removed during a VrOne pack. Deleted entitles are counted in GetLineCount

WsNum Workspace number (0-255)

Returns Number of lines in the workspace.

Example LineCount = Ws.GetLineCount (0)

GetLineMinMax (WsNum, LineNum)

Returns the minimum and maximum coordinate (minimum bounding rectangle) or an existing line.

WsNum Workspace number (0-255)

LineNum Line number (0-?)

Returns Minimum and maximum coordinate.

Example (MinX, MinY, MinZ, MaxX, MaxY, MaxZ) = Ws.GetLineMinMax (WsNum, LineNum)

GetLineLayer (WsNum, LineNum)

Returns the layer of an existing line. VrOne stores layer, mode and other header data in memory making it possible to scan VrOne files without loading entities from the disk. This makes searching much faster then loading all entities from disk. See the FindLayer12.py example above.

WsNum Workspace number (0-255)

LineNum Line number (0-?)

Returns Layer number (1-10,001)

Example Layer = Ws.GetLineLayer (WsNum, LineNum)

GetLineMode (WsNum, LineNum)

Returns the mode of an existing line. VrOne stores layer, mode and other header data in memory making it possible to scan VrOne files without loading entities from the disk. This makes searching much faster then loading all entities from disk. See the FindLayer12.py example above.

WsNum Workspace number (0-255)

LineNum Line number (0-?)

Returns Line mode (1=Line 2=Splined line)

Example Mode = Ws.GetLineMode (WsNum, LineNum)

DelLine (WsNum, LineNum)

Deletes a line on disk by setting its layer to a negative number. Pack Vr file (PacVr) removes these deleted entities.

WsNum Workspace number (0-255)

LineNum Line number (0-?)

Returns 0=Line was deleted 1=Line could not be deleted. WsNum or LineNum were out of range.

Example Ws.DelLine (WsNum, LineNum)

IsLineDeleted (WsNum, LineNum)

Checks if an existing line is deleted. A deleted entities layer number is zero or a negative layer number. Pack Vr file (PacVr) removes these deleted entities.

WsNum Workspace number (0-255)

LineNum Line number (0-?)

Returns 0=Line is not deleted 1=Line is deleted

Example if Ws.IsLineDeleted (WsNum, LineNum):

GetSymCount (WsNum)

Returns the number of symbols in a workspace. NOTE: Deleted entities are removed during a VrOne pack. Deleted entitles are counted in GetSymCount

WsNum Workspace number (0-255)

Returns Number of symbols in the workspace.

Example SymCount = Ws.GetSymCount (0)

GetSymLayer (WsNum, LineNum)

Returns the layer of an existing symbol. VrOne stores layer, mode and other header data in memory making it possible to scan VrOne files without loading entities from the disk. This makes searching much faster then loading all entities from disk. See the FindLayer12.py example above.

WsNum Workspace number (0-255)

SymNum Symbol number (0-?)

Returns Layer number (1-10,001)

Example Layer = Ws.GetLineLayer (WsNum, LineNum)

DelSym (WsNum, SymNum)

Deletes a line on disk by setting its layer to a negative number. Pack Vr file (PacVr) removes these deleted entities.

WsNum Workspace number (0-255)

SymNum Symbol number (0-?)

Returns 0=Symbol was deleted 1=Symbol could not be deleted. WsNum or SymNum were out of range.

Example Ws.DelSym (WsNum, SymNum)

IsSymDeleted (WsNum, SymNum)

Checks if an existing symbol is deleted. A deleted entities layer number is zero or a negative layer number. Pack Vr file (PacVr) removes these deleted entities.

WsNum Workspace number (0-255)

SymNum Symbol number (0-?)

Returns 0=Symbol is not deleted 1=Symbol is deleted

Example if Ws.IsSymDeleted (WsNum, LineNum):

GetTextCount (WsNum)

Returns the number of text labels in a workspace. NOTE: Deleted entities are removed during a VrOne pack. Deleted entitles are counted in GetSymCount

WsNum Workspace number (0-255)

Returns Number of text labels in the workspace.

Example TextCount = Ws.GetTextCount (0)

GetTextLayer (WsNum, LineNum)

Returns the layer of an existing text label. VrOne stores layer, mode and other header data in memory making it possible to scan VrOne files without loading entities from the disk. This makes searching much faster then loading all entities from disk. See the FindLayer12.py example above.

WsNum Workspace number (0-255)

TextNum Text number (0-?)

Returns Layer number (1-10,001)

Example Layer = Ws.GetTextLayer (WsNum, LineNum)

DelText (WsNum, TextNum)

Deletes a line on disk by setting its layer to a negative number. Pack Vr file (PacVr) removes these deleted entities.

WsNum Workspace number (0-255)

TextNum Text number (0-?)

Returns 0=Test was deleted 1=Text could not be deleted. WsNum or TextNum were out of range.

Example Ws.DelText (WsNum, TextNum)

IsTextDeleted (WsNum, LineNum)

Checks if an existing text label is deleted. A deleted entities layer number is zero or a negative layer number. Pack Vr file (PacVr) removes these deleted entities.

WsNum Workspace number (0-255)

TextNum Text number (0-?)

Return 0=Text is not deleted 1=Text is deleted

Example if Ws.IsTextDeleted (WsNum, TextNum):

UndoBegin (WsNum, Name)

Marks the beginning of an undo block. File operations between the UndoBegin and UndoEnd command may be undone.

NOTE: Each UndoBegin MUST be paired with an UndoEnd. Failure to match undo statements will cause unpredictable results. Undo commands may NOT be nested.

WsNum Workspace number (0-255)

Name Operation name for information only.

Example Ws.UndoBegin (WsNum, “ChangeLines”)

UndoEnd (WsNum)

Marks the end of an undo block. File operations between the UndoBegin and UndoEnd command may be undone.

NOTE: Each UndoBegin MUST be paired with an UndoEnd. Failure to match undo statements will cause unpredictable results. Undo commands may NOT be nested.

WsNum Workspace number (0-255)

Example Ws.UndoEnd (WsNum)

SetViewFlags (WsNum)

Set view flag for one window.

WsNum	Workspace to set view flag
returns	(ViewFlags)
	ViewFlags	List of flags, one for each window. Each entry is 0 or 1 indicating if Workspace is viewable or not in a particular window.

GetViewFlags (WsNum)

Gets workspace view flags for all windows

WsNum	Workspace index number.
returns	(ret)
	ret	List of flags, one for each window. Each entry is 0 or 1 indicating if Workspace is viewable or not in a particular window.

SetViewFlag (WsNum, Win, Viewable)

Set view flag for one window.

WsNum	Workspace index number.
Win	Window number 0 to MAX_WINS
Viewable	0=Workspace not viewable, 1=Workspace viewable

GetViewFlag (WsNum, Win)

Gets the view flag for one window.

WsNum	Workspace index number.
Win	Window number 0 to MAX_WINS
returns	(ret)
	ret	0=Workspace not viewable, 1=Workspace viewable

StartWsWrite (StartWs, EndWs, ShowWarning, WarningTitle)

Sets all inactive workspaces to writable. This is necessary if the user has the option set to keep inactive workspaces as read only, and the Python script is designed to change entities directly in inactive workspaces (without making the workspace active). A call to EndWsWrite should be made when processing is complete.

StartWs Starting workspace range (0-2000)

EndWs Ending workspace range (0-2000)

ShowWarning 0=Do not show warning if all workspaced are not writable. 1=Show warning if all workspaces are not writable.

WarningTitle Title string to display in warning dialog (only used if ShowWarning is set to 1, and all workspaces are not writable)

Returns 0=all workspaces are writable. –1=At least one workspace is not writable.

Example (stat) = Ws.StartWsWrite (0, Ws.GetWsCount()-1, 0, “”)

EndWsWrite (StartWs, EndWs)

Should be called after processing on inactive workspaces is complete. A call to StartWsWrite should be made before processing begins.

StartWs Starting workspace range (0-2000)

EndWs Ending workspace range (0-2000)

Example Ws.EndWsWrite (0, Ws.GetWsCount()-1)

SetReadOnly (WsNum, ReadOnly)

Set read only status for a workspace. Will fail when setting ReadOnly to 0 if file is open for write mode by another process. Use the GetReadOnly to verify state.

WsNum Workspce number to set read only status for.

ReadOnly 1=Set workspace to read only. 0=Set workspace to writable.

Example Ws.SetReadOnly (1, 0)

GetReadOnly (WsNum, ReadOnly)

Get read only status for a workspace.

WsNum Workspce number to set read only status for.

Returns 1=Set workspace to read only. 0=Set workspace to writable.

Example # Print read only status of all workspaces

Ws = PyVrWs()

for i in range (0, Ws.GetWsCount()-1):

print Ws.GetReadOnly(i), Ws.GetFileName (i)