smtrace Module

smtrace module is used along with vtkSMTrace to generate Python trace for ParaView. While this module is primarily designed to be used from the ParaView GUI, Python scripts can use this module too to generate trace from the script executed.

Typical usage is as follows:

from paraview import smtrace
config = smtracer.start_trace()

# config is an instance of vtkSMTrace. One can setup properties on this
# object to control  the generated trace. e.g.
config.SetFullyTraceSupplementalProxies(True)

# do the actions to trace.
    ...

# stop trace. The generated trace is returned.
txt = smtracer.stop_trace()

Developer Documentation

This section describes the module design for developers wanted to extend this module or use this module for advance tracing/state generation.

The design can be described as follows:

C++ code (either in ServerManager or the GUI layer) should trace actions. This is done using SM_SCOPED_TRACE() macro provided by vtkSMTrace. When tracing is enabled, each SM_SCOPED_TRACE() call creates a TraceItem. The TraceItem instance is scoped, i.e. the object is finalized and destroyed when the scope exits.

There are various types of TraceItem, ranging from those that trace specific action such as Show, or those that trace any modified properties (PropertiesModified). Generic TraceItem types, such as CallMethod and CallFunction can be used to trace methods called on vtkObject instances or functions in the global namespace.

TraceItems create or use Accessor instances. Accessors are objects created for Proxies and Properties in ParaView. Accessor knows how to access that proxy or property in the Python trace. TraceItems that create new proxies such as RegisterPipelineProxy and RegisterViewProxy, create new ProxyAccessor instances. Other such as PropertiesModified trace item rely on accessors already created. Trace can provide access to already created accessor as well as create new accessor for proxies create before the tracing began (Trace.get_accessor()).

Additionally, there are filters such as ProxyFilter, PipelineProxyFilter, etc. which are used to filter properties that get traced and where they get traced i.e. in constructor call or right after it.

Notes about references

RealProxyAccessor keeps a hard reference to the servermanager.Proxy instance. This is required. If we don’t, then the Python object for vtkSMProxy also gets garbage collected since there’s no reference to it.

class paraview.smtrace.Accessor(varname, obj)

Bases: object

finalize()

get_object()

class paraview.smtrace.AnimationProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

class paraview.smtrace.BlockTraceItems

Bases: paraview.smtrace.NestableTraceItem

Item to block further creation of trace items, even those that are NestableTraceItem. Simply create this and no trace items will be created by _create_trace_item_internal until this instance is cleaned up.

class paraview.smtrace.BookkeepingItem

Bases: paraview.smtrace.NestableTraceItem

Base class for trace items that are only used for book keeping and don’t affect the trace itself.

class paraview.smtrace.CallFunction(functionname, *args, **kwargs)

Bases: paraview.smtrace.TraceItem

class paraview.smtrace.CallMethod(proxy, methodname, *args, **kwargs)

Bases: paraview.smtrace.TraceItem

get_trace(proxy, methodname, args, kwargs)

classmethod marshall(x)

class paraview.smtrace.CallMethodIfPropertiesModified(proxy, methodname, *args, **kwargs)

Bases: paraview.smtrace.CallMethod

Similar to CallMethod, except that the trace will get logged only if the proxy fires PropertiesModified event before the trace-item is finalized.

finalize()

on_event(obj, string)

class paraview.smtrace.ChooseTexture(owner, texture, prop)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Traces changes of texture object selection. For example renderview background.

class paraview.smtrace.CleanupAccessor(proxy)

Bases: paraview.smtrace.BookkeepingItem

finalize()

class paraview.smtrace.CreateAnimationTrack(cue)

Bases: paraview.smtrace.TraceProxy

class paraview.smtrace.CreateExtractor(xmlname, producer, extractor, registrationName, comment=None)

Bases: paraview.smtrace.TraceItem

Traces creation of extractors

finalize()

class paraview.smtrace.Delete(proxy)

Bases: paraview.smtrace.TraceItem

This traces the deletion of a Pipeline proxy

class paraview.smtrace.ExodusIIReaderFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.PipelineProxyFilter

should_never_trace(prop)

overridden to avoid hiding “non-gui” properties such as FileName.

class paraview.smtrace.ExportView(view, exporter, filename)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

class paraview.smtrace.ExporterProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

should_trace_in_ctor(prop)

class paraview.smtrace.ExtractSelectionFilter(trace_all_in_ctor=False, save_selection=False)

Bases: paraview.smtrace.PipelineProxyFilter

should_never_trace(prop)

overridden to avoid hiding “non-gui” properties such as FileName.

class paraview.smtrace.ExtractorFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

should_trace_in_ctor(prop)

class paraview.smtrace.Hide(producer, port, view)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Traces Hide

class paraview.smtrace.ImportView(view, importer, filename)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

class paraview.smtrace.LoadPlugin(filename, remote)

Bases: paraview.smtrace.TraceItem

class paraview.smtrace.LoadState(filename, options)

Bases: paraview.smtrace.TraceItem

finalize()

class paraview.smtrace.NestableTraceItem

Bases: paraview.smtrace.TraceItem

Base class for trace item that can be nested i.e. can trace when some other trace item is active.

class paraview.smtrace.PipelineProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

overridden to avoid hiding “non-gui” properties such as FileName.

should_trace_in_create(prop)

should_trace_in_ctor(prop)

class paraview.smtrace.PropertiesModified(proxy, selector=None, comment=None)

Bases: paraview.smtrace.NestableTraceItem

Traces properties modified on a specific proxy.

finalize()

class paraview.smtrace.PropertyTraceHelper(propertyname, proxyAccessor)

Bases: object

PropertyTraceHelper is used by RealProxyAccessor to help with tracing properites. In its constructor, RealProxyAccessor creates a PropertyTraceHelper for each of its properties that could potentially need to be traced.

create_multiline_string(astr)

helper to convert a string representation into a multiline string

finalize()

get_object()

Returns the servermanager.Property (or subclass) for the vtkSMProperty this trace helper is helping with.

get_property_name()

get_property_trace(in_ctor)

return trace-text for the property.

Parameters

in_ctor – If False, the trace is generated trace will use fully-scoped name when referring to the property e.g. sphere0.Radius=2, else it will use just the property name, e.g., Radius=2.

get_property_value()

Return the Property value as would be returned by servermanager.Proxy.GetPropertyValue().

get_proxy()

get_value()

Returns the property value as a string. For proxy properties, this will either be a string used to refer to another proxy or a string used to refer to the proxy in a proxy list domain.

get_varname(not_fully_scoped=False)

Returns the variable name to use when referring to this property.

Parameters

not_fully_scoped – If False, this will return fully-scoped name when referring to the property e.g. sphere0.Radius, else it will use just the property name, e.g., Radius.

has_proxy_list_domain()

Returns True if this property has a ProxyListDomain, else False.

paraview.smtrace.ProxyAccessor(*args, **kwargs)

class paraview.smtrace.ProxyFilter(trace_all_in_ctor=False)

Bases: object

should_never_trace(prop, hide_gui_hidden=True)

should_trace_in_create(prop, user_can_modify_in_create=True)

should_trace_in_ctor(prop)

class paraview.smtrace.RealProxyAccessor(varname, proxy)

Bases: paraview.smtrace.Accessor

classmethod create(*args, **kwargs)

finalize()

get_ctor_properties()

Returns a list of property accessors that should be specified in the constructor.

get_properties()

get_property(name)

is_ctor_property(prop)

classmethod register_create_callback(function)

trace_ctor(ctor, filter, ctor_args=None, skip_assignment=False, ctor_var=None, ctor_extra_args=None)

trace_properties(props, in_ctor)

classmethod unregister_create_callback(function)

class paraview.smtrace.RegisterLayoutProxy(layout)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

finalize(filter=None)

class paraview.smtrace.RegisterLightProxy(proxy, view=None)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Traces creation of a new light (vtkSMParaViewPipelineController::RegisterLightProxy).

finalize()

class paraview.smtrace.RegisterPipelineProxy(proxy, saving_state=False)

Bases: paraview.smtrace.TraceItem

This traces the creation of a Pipeline Proxy such as sources/filters/readers etc.

finalize()

class paraview.smtrace.RegisterSelectionProxy(proxy)

Bases: paraview.smtrace.TraceItem

This traces the creation of a Proxy for selection. This is used only when saving state for now.

finalize()

class paraview.smtrace.RegisterTextureProxy(proxy, filename, trivial_producer_key, proxyname)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Traces creation of a new texture (vtkSMParaViewPipelineController::RegisterTextureProxy)

finalize()

class paraview.smtrace.RegisterViewProxy(proxy)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Traces creation of a new view (vtkSMParaViewPipelineController::RegisterViewProxy).

finalize()

class paraview.smtrace.RenameProxy(proxy)

Bases: paraview.smtrace.TraceItem

Trace renaming of a source proxy.

finalize()

class paraview.smtrace.RenderingMixin

Bases: object

property skip_from_trace

class paraview.smtrace.RepresentationProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.PipelineProxyFilter

should_never_trace(prop)

overridden to avoid hiding “non-gui” properties such as FileName.

should_trace_in_create(prop)

for representations, we always trace the ‘Representation’ property, even when it’s same as the default value (see issue #17196).

should_trace_in_ctor(prop)

class paraview.smtrace.SaveAnimationExtracts(proxy)

Bases: paraview.smtrace.TraceItem

Used by vtkSMSaveAnimationExtractsProxy to trace saving of extracts generation.

class paraview.smtrace.SaveCameras(proxy=None, **kwargs)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.BookkeepingItem

This is used to request recording of cameras in trace

classmethod get_trace(proxy=None)

class paraview.smtrace.SaveData(writer, filename, source, port)

Bases: paraview.smtrace.TraceItem

class paraview.smtrace.SaveExtractsFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_trace_in_ctor(prop)

class paraview.smtrace.SaveLayoutSizes(proxy=None)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.BookkeepingItem

A bookkeeping item to trace sizes for all layouts used by the trace (or the one explicitly passed to the constructor).

This ensures that all the layouts (and consequently views in those layout) are setup with sizes similar to those in the UI (BUG #20102).

classmethod get_trace(proxy=None)

class paraview.smtrace.SaveScreenshotOrAnimation(helper, filename, view, layout, mode_screenshot=False, location=16)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

class paraview.smtrace.ScalarBarInteraction(proxy, comment=None)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.NestableTraceItem

Traces scalar bar interactions

finalize()

class paraview.smtrace.ScalarBarProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

should_trace_in_ctor(prop)

class paraview.smtrace.ScreenShotHelperProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

should_trace_in_ctor(prop)

class paraview.smtrace.SetBlocksScalarColoring(display, block_selectors, arrayname, attribute_type, component=None, separate=False, luts=None)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Trace vtkSMPVRepresentationProxy.SetBlocksScalarColoring

finalize()

class paraview.smtrace.SetCurrentProxy(selmodel, proxy, command)

Bases: paraview.smtrace.TraceItem

Traces change in active view/source etc.

class paraview.smtrace.SetScalarColoring(display, arrayname, attribute_type, component=None, separate=False, lut=None)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Trace vtkSMPVRepresentationProxy.SetScalarColoring

finalize()

class paraview.smtrace.Show(producer, port, view, display, comment=None)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Traces Show

finalize()

paraview.smtrace.SupplementalProxy(cls)

This function decorates a ProxyFilter. Designed to be used for supplemental proxies, so that we can centralize the logic to decide whether to trace any of the properties on the supplemental proxies the first time that proxy is accessed.

class paraview.smtrace.TimeKeeperProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

class paraview.smtrace.Trace

Bases: object

Output = None

classmethod create_accessor(obj, selector=None)

Create a new accessor for a proxy. This returns True when a ProxyAccessor has been created, other returns False. This is needed to bring into trace proxies that were either already created when the trace was started or were created indirectly and hence not explicitly traced.

classmethod get_accessor(obj, selector=None)

Returns an accessor for obj. If none exists, a new one may be created, if possible. Currently obj is expected to be a servermanager.Proxy instance. In the future, we may change this to be a vtkSMProxy instance instead.

classmethod get_registered_name(proxy, reggroup)

Returns the registered name for proxy in the given reggroup.

classmethod get_varname(name)

returns a unique variable name given a suggested variable name. If the suggested variable name is already taken, this method will try to find a good suffix that’s available.

classmethod has_accessor(obj)

classmethod register_accessor(accessor)

Register an instance of an Accessor or subclass

classmethod rename_separate_tf_and_get_representation(arrayName, selector=None)

classmethod reset()

Resets the Output and clears all register accessors.

classmethod unregister_accessor(accessor)

class paraview.smtrace.TraceAnimationProxy(proxy)

Bases: paraview.smtrace.RenderingMixin, paraview.smtrace.TraceItem

Traces all changes in an animation proxy.

finalize()

class paraview.smtrace.TraceItem

Bases: object

finalize()

class paraview.smtrace.TraceOutput(data=None)

Bases: object

Internal class used to collect the trace output. Everytime anything is pushed into this using the append API, we ensure that the trace is updated. Trace doesn’t put commands to the trace-output as soon as modifications are noticed to try to consolidate the state changes.

append(data)

append_separated(data)

append_separator()

raw_data()

reset()

class paraview.smtrace.TraceProxy(proxy, filter, description)

Bases: paraview.smtrace.TraceItem

Traces all changes in a provided proxy.

finalize()

class paraview.smtrace.TraceText(text, *args, **kwargs)

Bases: paraview.smtrace.TraceItem

Add text directly to the trace. For paraview client applications to use with non-proxy objects.

class paraview.smtrace.TransferFunctionProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

should_trace_in_ctor(prop)

exception paraview.smtrace.Untraceable(logmessage='<unspecified>')

Bases: Exception

class paraview.smtrace.ViewProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

class paraview.smtrace.WriterProxyFilter(trace_all_in_ctor=False)

Bases: paraview.smtrace.ProxyFilter

should_never_trace(prop)

should_trace_in_ctor(prop)

paraview.smtrace.get_current_trace_output(raw=False)

Returns the trace generated so far in the tracing process.

paraview.smtrace.get_current_trace_output_and_reset(raw=False)

Equivalent to calling the following code:

get_current_trace_output(raw) reset_trace_output()

paraview.smtrace.reset_trace_output()

Resets the trace output without resetting the tracing datastructures themselves.

paraview.smtrace.start_trace(preamble=None)

Starting tracing. On successful start, will return a vtkSMTrace object. One can set tracing options on it to control how the tracing. If tracing was already started, calling this contine with the same trace.

paraview.smtrace.stop_trace()

Stops the trace and returns the generated trace output string.