3 \page tui_page Using salome.py module
5 The Python module salome.py provides a functionality to access main
6 SALOME features from the Python console (either embedded in GUI
7 desktop or external one).
9 To use salome.py module, import it into the Python interpreter and
10 initialize it by calling \c salome_init() function:
17 The salome.py Python module provides a set of variables and functions
18 allowing access to different elements of the current SALOME
19 session (this Python interpreter is connected to).
20 This page gives a short description of most useful variables and
23 \li \b orb Reference to the CORBA::ORB instance
25 This variable can be used to initialize different CORBA-related
26 elements of the SALOME session (for example, naming service, etc).
27 For example, to get an access to the SALOME naming service, you can
28 use the following commands:
30 import SALOME_NamingServicePy
31 NS = SALOME_NamingServicePy.SALOME_NamingServicePy_i(salome.orb)
34 The \b orb variable is also useful when it is necessary to convert
35 CORBA reference object to its string representation (IOR) and vice
38 studyIOR = salome.orb.object_to_string(salome.myStudy)
39 study = salome.orb.string_to_object(studyIOR)
40 is_same = salome.myStudy._is_equivalent(study) # is_same = True
43 \li \b naming_service SALOME naming service instance
45 This variable can be used to register/find objects created in a
46 distributed environment. For example, to get access to the SALOME
47 Module Catalog server, use \c Resolve() method:
49 import SALOME_ModuleCatalog
50 mc = salome.naming_service.Resolve('/Kernel/ModulCatalog')
53 Similarly, method \c Register() can be used to register objects
54 in the naming service:
56 salome.naming_service.Register(myObject,'/My/Object/Path')
57 o = salome.naming_service.Resolve('/My/Object/Path')
58 is_same = myObject._is_equivalent(o) # is_same = True
61 \li \b lcc Life Cycle CORBA class instance
63 This object can be used to get access to CORBA engine part of some
64 SALOME module, available in the current SALOME session. The following
65 code returns a reference to the Geometry module engine, loading it if
69 geom = salome.lcc.FindOrLoadComponent('FactoryServer', 'GEOM')
71 \b Note, that in the above example, \e "FactoryServer" is a name of the
72 SALOME container, where Geometry module engine should be loaded.
74 \li \b myStudyManager Reference to the study manager
76 SALOMEDS Study manager is used to manipulate with the studies: create,
77 open, save, close. It also can be used to find the study by its
78 numerical ID or name. The code below demonstrates main
79 functionalities of a study manager:
81 # create new study with the name "MyStudy"
82 new_study = salome.myStudyManager.NewStudy("MyStudy")
84 # open study from file /home/user/MyStudy.hdf
85 study = salome.myStudyManager.OpenStudy("/home/user/MyStudy.hdf")
88 salome.myStudyManager.Save(study, False) # not using multifile save mode
90 # save study in ASCII format
91 salome.myStudyManager.SaveASCII(study, True) # using multifile save mode
93 # save study with the new file path
94 salome.myStudyManager.SaveAs("/home/user/MyStudy.hdf", study, False)
96 # save study with the new file path in ASCII format
97 salome.myStudyManager.SaveAsASCII("/home/user/MyStudy.hdf", study, False)
100 salome.myStudyManager.Close(study)
102 # get list of all opened studies
103 studies = salome.myStudyManager.GetOpenStudies()
105 # find study by its numerical ID (integer value starting from 1)
106 study = salome.myStudyManager.GetStudyByID(studyID)
108 # find study by its name
109 study = salome.myStudyManager.GetStudyByName("/home/user/MyStudy.hdf")
114 \li \b myStudy Reference to the current (active) study
116 This variable can be used to manipulate with the date of the study:
117 create data tree, assign attributes of different types to the objects
118 in a data tree, create references between objects, etc.
120 \b Note, that the term "active" or "current" study does not make much
121 sense outise the GUI Python console. When working in GUI, user always
122 deals with one only top-level study, which desktop is currently on the
123 top if the windows stack. This is what is called \e "active study".
124 In TUI mode (without GUI or outside GUI), user has to manipulate with
125 studies manually; no any special control for the life cycle of the
126 study is done. In TUI mode, \c salome.muStudy variable is an instance
127 of the first study created when you call salome_init() function.
129 The following code demonstrates some examples of \c salome.myStudy
130 variable usage. For more details please refer to the SALOMEDS.idl file
135 studyName = salome.myStudy._get_Name()
137 # get study numerical ID
138 studyID = salome.myStudy._get_StudyId()
140 # find SALOMEDS component by its type
141 scomponent = FindComponent("MyComponent")
143 # find SALOMEDS component by its entry ID
144 scomponent = FindComponentID("0:1:1") # "0:1:1" is a component ID
146 # find SALOMEDS object by its name (first found object is returned)
147 sobject = salome.myStudy.FindObject("MyObject")
149 # find SALOMEDS object by its entry ID
150 sobject = salome.myStudy.FindObjectID() # "0:1:1:1" is an object ID
152 # find SALOMEDS object by its IOR attribute
153 sobject = salome.myStudy.FindObjectIOR(IOR)
155 # find SALOMEDS object by its path in the data tree
156 sobject = salome.myStudy.FindObjectByPath("/MyComponent/MyObject/MySubObject")
158 # get SALOMEDS object's path in a study data tree
159 sobject_path = salome.myStudy.GetObjectPath(sobject)
161 # get study properties
162 prop = salome.myStudy.GetProperties()
163 prop.GetCreationDate() # get creation date
164 prop.IsModified() # check if study has been modified (and not yet saved)
165 prop.SetLocked(True) # lock the study (prohibit modifications)
166 prop.IsLocked() # check if study is locked
168 # create objects with study builder
169 builder = salome.myStudy.NewBuilder() # create builder
170 comp = builder.NewComponent("MyComponent") # create a component of the "MyComponent" type
171 attrName = builder.FindOrCreateAttribute(comp, "AttributeName")
172 attrName.SetValue("MyComponent") # set name to the component
173 object = builder.NewObject(comp) # create new object, a child of the component
174 attrName = builder.FindOrCreateAttribute(object, "AttributeName")
175 attrName.SetValue("MyObject") # set name to the object
176 attrInt = builder.FindOrCreateAttribute(object, "AttributeInteger")
177 attrInt.SetValue(123) # assign integer attribute to the object
178 attrIOR = builder.FindOrCreateAttribute(object, "AttributeIOR")
179 attrIOR.SetValue(IOR) # assign IOR attribute to the object (to point to some CORBA object)
181 # iterate through objects of the data tree with child iterator
182 iter = salome.myStudy.NewChildIterator(comp) # initialize from the component
183 iter.InitEx(True) # init recursive mode
193 \li \b myStudyId Identifier of the current (active) study
195 This variable contains the numerical identifier of the current
196 (active) study. It is an equivalent of \c
197 salome.myStudy._get_StudyId() code.
199 \li \b myStudyName Name of the current (active) study
201 This variable contains the name of the current (active) study. It is
202 an equivalent of \c salome.myStudy._get_Name() code.
204 \li \b DumpStudy() Print study contents
206 This function prints the study data object tree to the terminal
207 window. The output for each object includes its entry ID, name, IOR
208 (if there is one) and referenced object ID (for references). I.e.
209 this is the same data the user can see in the Object Browser columns.
211 salome.DumpStudy(salome.myStudy)
214 \li \b IDToSObject() Get SALOMEDS object by its entry ID.
216 This function checks if the SObject with the specified entry ID exists
217 in the current study and returns it. Otherwise \c None is returned.
219 sobject = salome.IDToSObject("0:1:1:1") # "0:1:1:1" is an object ID
221 Actually this function is just a shortcut to the following code:
223 sobject = salome.myStudy.FindObjectID("0:1:1:1")
226 \li \b IDToObject() Get CORBA object by its entry ID.
228 This function checks if the SObject with the specified entry ID exists
229 in the current study, then retrieves IOR attribute from it and,
230 finally, if IOR is not empty, returns CORBA object corresponding to
233 object = salome.IDToObject("0:1:1:1") # "0:1:1:1" is an object ID
235 Actually this function is just a shortcut to the following code:
237 sobject = salome.myStudy.FindObjectID("0:1:1:1")
239 object = sobject.GetObject()
244 \li \b ObjectToSObject() Get SALOMEDS object corresponding to the
247 This function finds an object in the current study which corresponds
248 to the specified CORBA object (i.e. it has IOR attribute, pointing to
249 the CORBA object). If there is no corresponding SALOMEDS object in the
250 study, \c None is returned:
252 sobject = salome.ObjectToSObject(object)
254 Actually this function is just a shortcut to the following code:
256 ior = salome.orb.object_to_string(object)
257 sobject = salome.myStudy.FindObjectIOR(ior)
260 \li \b ObjectToID() Get SALOMEDS object entry ID corresponding to the
263 This function finds an object in the current study which corresponds
264 to the specified CORBA object (i.e. it has IOR attribute, pointing to
265 the CORBA object). If the object is found, its entry ID is returned,
266 otherwise empty string is returned:
268 entry = salome.ObjectToID(object)
270 Actually this function is just a shortcut to the following code:
272 ior = salome.orb.object_to_string(object)
273 sobject = salome.myStudy.FindObjectIOR(ior)
275 entry = sobject.GetID()
280 \li \b createNewStudy() Create new study
282 This function can be used to create new SALOME study. Returns an ID of
285 studyId = salome.createNewStudy()
286 study = salome.myStudyManager.GetStudyByID(s)
289 \li \b generateName() Generate unique name
291 This function adds random numerical suffix to the passed string
292 parameter ("Study" by default) and returns the resulting string:
294 name_1 = salome.generateName() # name_1 is something like "Study682"
295 name_1 = salome.generateName("Obj") # name_1 is something like "Obj32"
298 \li \b sg SWIG interface to the SALOME GUI
300 This variable provides an access to some GUI functions.
302 \b Note, that this variable is not available if you use salome.py
303 Python module outside the GUI desktop, i.e. not in the embedded Python
304 console (since SWIG library is linked directly to the GUI library).
306 The example of usage:
308 # update Object browser contents
309 salome.sg.updateObjBrowser(True)
311 # get active study ID
312 studyId = salome.sg.getActiveStudyId()
314 # get active study name
315 studyName = salome.sg.getActiveStudyName()
317 # get selected objects
318 selCount = salome.sg.SelectedCount() # total number of selected items
319 for i in range(selCount):
320 print salome.sg.getSelected(i) # print entry ID of i-th selected item
322 # get list of all selected objects' IDs
323 selected = salome.sg.getAllSelected()
325 # add object to the selection
326 salome.sg.AddIObject("0:1:1:1") # "0:1:1:1" is an object ID
328 # remove object from the selection (make it unselected)
329 salome.sg.RemoveIObject("0:1:1:1") # "0:1:1:1" is an object ID
331 # clear selection (set all objects unselected)
332 salome.sg.ClearIObjects()
334 # display object in the current view (if possible)
335 salome.sg.Display("0:1:1:1") # "0:1:1:1" is an object ID
336 salome.sg.UpdateView() # update view
338 # erase object from the current view
339 salome.sg.Erase("0:1:1:1") # "0:1:1:1" is an object ID
340 salome.sg.UpdateView() # update view
342 # display all objects in the current view (if possible)
343 salome.sg.DisplayAll()
344 salome.sg.UpdateView() # update view
346 # erase all objects from the current view
348 salome.sg.UpdateView() # update view
350 # set top, bottom, front, rear, left, right view
351 salome.sg.ViewTop() # top view
352 salome.sg.ViewBottom() # bottom view
353 salome.sg.ViewFront() # front view
354 salome.sg.ViewTop() # back view
355 salome.sg.ViewLeft() # left view
356 salome.sg.ViewRight() # right view
359 salome.sg.ResetView()
361 # get component symbolic name by its user name
362 compName = salome.sg.getComponentName("Geometry") # compoName = "GEOM"
364 # get component user name by its symbolic name
365 compName = salome.sg.getComponentUserName("SMESH") # compoName = "Mesh"