Filters Renaming and Categories Update

Goal

Make it easier to discover the filters and to choose the correct one in the GUI and in python.
Thus the following is about the proxy labels, not names, even if we may use the term “name” for simplicity.

Constraints

Backward compatibility

The names are used in the statefiles and the labels in the python scripts, thus we need to care about backward compatibility. We are currently completing the support for python compatibility mode.

Also renaming has an impact for the current users so we may want to limit the number of changes.

Context

This is not an exhaustive work: we have targeted a subset of data-array-oriented filters.Thus a lot of meshing filters and data extraction filters were not considered.

Proposition

Suggested rules

  1. Labels should start with a verb.
  2. Changes should follow the Law of Proximity:
    a. improve naming consistency
    b. put similar filters into categories
    c. group categories (in a tree)

Some verbs are already used in several cases, and I mainly reused them in my suggestion below:

  • Generate
  • Compute

In my opinion, the difference that may be suggested here depends mainly on the complexity of the computation, and therefor on how this computation is dependent on the input data.

Examples:

  1. BlockScalars is really easy to compute: may become GenerateBlockIds
  2. Connectivity requires topology knowledges: ComputeConnectivity

I’m not suggesting to rename every filters with one of those verbs, this is more a guideline.

Also, I’m of course open to suggestions: Does this kind of classification make any sense to you ? Do you have better wording ?


EDIT

This is in fact to mitigate. While using a verb to describe a filter action can make sense, it looks better to have only meaningful word, and drop too generic ones. See comments below.


Naming and categories

Legend

# Category
  ## Sub category
    Filter
    RenamedFilter (CurrentName)

Current categories

# AMR
# Annotation
# Chemistry
# Common
# CosmoTools
# CTH
# Data Analysis
# Hyper Tree Grid
# Material Analysis
# Moment Invariants
# Point Interpolation
# Quadrature Points
# Statistics
# Temporal

Proposition

Contained filters are listed only for new categories.

EDIT

updated version after some discussion

# Common
-> kept for toolbar

# Data Model
  ## AMR
(  ## CTH)
  ## Molecules (Chemistry)
  ## Hyper Tree Grid

# Display
  ## Annotation
  ## Textures
    SurfaceNormals (GenerateSurfaceNormals)
    SurfaceTangents (GenerateSurfaceTangents)
    TextureMapToCylinder
    TextureMapToPlane
    TextureMapToSphere
  ## Charts
    Histogram
    Histogram 2D
    Plot Data
    Plot Data Over Time
    Plot Global Variables Over Time
    Plot On Intersection Curves ~
    Plot On Sorted Lines ~
    Plot Over Line

# Domain
(  ## CosmoTools)
  ## (Data Analysis)
   -> kept for toolbar, but duplicated into Mesh Extraction and Charts

  ## Distributed
    D3
    DistributeDataSet ~ (RedistributeDataSet)
    DistributePoints
    GhostCellsGenerator
    GhostElementsSuppresion ~ (RemoveGhostInformation)
    ProcessIds (GenerateProcessIds)

(  ## Material Analysis)
  ## Moment Invariants
  ## Point Interpolation
  ## Quadrature Points
  ## Temporal

# Mesh
  ## Mesh Analysis
    CellSize
    CellValidity (ValidateCells)
    ConnectedSurfaceProperties (ComputeConnectedSurfaceProperties)
    Connectivity
    Coordinates (AppendLocationAttributes)
    CountCellFaces
    CountCellVertices
    Elevation
    PolyLineLength (AppendArcLength)
    MeshQuality
    SurfaceCurvature (Curvature)

  ## Mesh Extraction
    Extract Cells Along line
    Extract Cells Along Lines Custom Source
    Extract Cells By Type
    Extract Location
    Extract Selection
    Probe Location

# Programmable
  Calculator
  ProgrammableAnnotation
  ProgrammableFilter
  ProgrammableSource
  PythonCalculator

# Data Arrays
  ## Arrays Generation
    Elevation
    PerlinNoise
    RandomAttributes
    RandomVectors
    SpatioTemporalHarmonics (GenerateSpatioTemporalHarmonics)

  ## Arrays Forwarding
    AppendAttributes
    CellDataToPointData
    FieldArraysFromFile (AddFieldArrays)
    PassArrays
    PointDataToCellData
    RenameArrays

  ## Arrays Quality
    ConstrainVectorsOnSurface ~ (SurfaceVectors)
    DeflectsNormal
    Derivatives (ComputeDerivatives)
    Gradient
    TensorPrincipalInvariants (ComputeTensorPrincipalInvariants)
    YieldCriteria (ComputeYieldCriteria)

  ## Element Ids
    AMRLevelIds (LevelScalarsOverlappingAMR)
    BlockIds (BlockScalars)
    Connectivity
    GlobalIds (GenerateGlobalIds)
    Ids (GenerateIds)
    ProcessIds (GenerateProcessIds)

  ## Statistics
2 Likes

@mwestphal @cory.quammen FYI

Better organization is always a good idea, just make sure that paraview documentation is also updated.

1 Like

I’m not sure if I totally understand, however, I would recommend two things.

  • Everything should be in alphabetical order. If not, it is REALLY hard to find filters. See DeflectsNormal above.
  • Think in terms of users. If “Mesh Anaysis” is what users would naturally look for, it’s good. If “Data Analysis”, or “CTH”, the new proposal isn’t as good.
    Alan

Alphabetical sort will be ensured by automatic code, so no risk of “I changed my mind just before posting and forget to move it” :slight_smile:

Also, in this first proposition, I did not rename existing categories. Maybe I should ? After some though, I think yes.

This is indeed the hard part of the game here :slight_smile:

1 Like

I’m not sure I understand this proposal, but I think I hate it.

The suggestion of having all labels starting with a verb kind of made sense until we get to the part of the suggestion to add words like “Generate” or “Compute”. These verbs are worthless. Nearly all filters compute and generate things. And there is no real difference between them. Why would you compute something to not generate it? How do you generate something without computing it? Are normals generated because they are a feature of a polygon or computed because you have to do a cross product and normalization? Oh s***, what would happen if you had a GenerateNormals and ComputeNormals? Oh God, don’t let this hell on Earth come to pass!

I would suggest the opposite: remove general verbs like generate and compute that are obvious from the context.

For the same reason, I’m not thrilled with the proposed top-level filter categories. I will be forever confused between Analysis and Generation. Why is RenameArrays analysis but Programmable Filter generation?

I won’t dispute that filters should be named with more consistency than they have now, or that they could be recategorized. But considering your stated goal, I think time could be more effectively invested in improving the filter search feature (Filters → Search…).

One idea is to search the content of the ParaView Online Help (Help → Reader, Filter, and Writer Reference) to determine the list of filters to show. Matches of the search term to the documentation of a filter should mean that filter should appear in the list of filters presented to the user. It would be great to also show the documentation of the filter in that search menu.

I like the proposal to start with sensible verbs. I’m not sure “compute” is useful at all, “generate” implies something is created, but why not use “add” for filters that add a field to the output, for example. “Add Surface Normals”, “Add Global Ids”, “Add Gradient”. My 2 cents.

Let me rephrase my main goal:
making filters discoverable for beginners

I think discovery happens often by clicking on buttons and menus. I would like to explore:

  1. better naming: meaningful words and consistency helps a lot to know what a filter does
  2. better organization: you do not want to parse a list of ~200 elements each time you want to know if a filter exists

Improving Quick Launch and Filter Reference is another good point but comes in a second time (and is outside of the scope of my current work)

Thanks to your inputs, I’ll come back very soon with an update.

I have a suggestion regarding filters naming, coming from years of text editor usages that I won’t name here to avoid any out-of-context debate :slight_smile: This thread is only about naming and does not address the category / sorting of the filters at all.

This is mainly an answer to the first section:

Labels should start with a verb.

In practice, English language tends to start with the subject and then the action. In the computer realm, having the selection first, then the action is also convenient, and I think this stays true in ParaView.

To fully address this naming, I would like to propose a grammar to drive the order of the information in the name. Each block is optional of course. Feel free to discuss / change it as I am not a UX expert.

[Input domain][output domain][filter result][meta info][verb]

input domain

The kind of input supported by this filter. For example, a filter working on HTG to create cell center is Hyper Tree Grid Cell Centers.
A filter that would slice an image would be: Image Slicer.
Filters with an obvious or generic enough input do no need to specify this. We do not want a Data Sets Appender.

A nice thing here would also be to have filters alphabetically close to each other when operating on a same input. This also helps the user understand why some filters may be disabled all together if the selected object in the pipeline does not have the required type.

output domain

The kind of output supported by this filter, usually prefixed by To. For example, a filter transforming a HTG into an unstructured grid would be a: Hyper Tree Grid To Unstructured Grid.
A filter transforming an image data into a point set would be a Image Data To Point Set.
Filters acting as a pass-through or with an obvious output type may omit this part.

filter result

This fields bring the main semantic of the filter processing. It seems that, except for filters only meant for type conversion / resampling, this part is already given. For example a filter that computes the normals is Surface Normals. Adding a elevation field ? Elevation.

meta info

Here, this would mainly be to add semantic around temporal and distributed abilities of the filters (and maybe more things I did not think about).
All filter that traverse time steps to generate a non temporal output could have a Over Time indication here. Example: Plot Data Over Time.
Filters requiring distributed datasets may also have a specific indicator here, like Distributed (I would love to find a better word here).

verb

This last part if mostly an indication of performance, as a way to give a hint if the filter is just adding a new field or recreating the whole geometry. A filter that add a new field could be a Hyper Tree Grid Ghost Cells Generator for example.
A filter that rebuild a smaller geometry from an existing one could be a Surface Extractor.

Some remarks

I tried to illustrate the proposed grammar with already existing filters that already fulfill it, as a way to show that it is kinda intuitive. There are still a number of filters that would need changes if we adopt it.
For example, with the proposed syntax we would not keep the Convert To… filters as it means having the output type after the result. So we would have a generic converter syntax, with PolyData To Molecule, or To Cell Grid. I do not know if we should have a Data Set To Cell Grid in that case for example.

3 Likes

Some combative comments:

I think I see where you are going with this, but I don’t think it will serve to make filters discoverable for novice users. The distinction between “Add” and “Generate” and “Compute” is still subtle. And filters often seem to “add” things that are not an extra field. The Angular Periodic Filter “adds” wedges of data. The Glyph filter adds a bunch of icons. I know this is not what you described as “add”, but I can’t imagine a new user understanding the distinction.

I think we are too focused on words being verbs for a variety of reasons:

  1. That unnecessarily constrains the way we describe filters. I refuse to believe that Calculate an Expression is a better name than Calculator.

  2. English speakers are adept at shifting nouns to verbs (e.g., I bet you “googled” something recently). If teenagers had to generate surface lighting, we would all be talking about normaling our data.

  3. Often the action the filter takes is not unique. The filter should lead with what makes its action unique.

We should focus on words that best describe what a filter does regardless of what place that word takes in the list.

I don’t think starting the filter name with the input/output domain is best. In fact, I would put that at the end. One main problem is that many filters don’t have a specific input or output type. So, not only do I have to know the type of my data, I have to know if the filter I am looking for applies only to my type of data, some subset of types that include my data, or any data type. That would be hard for me and impossible for novices.

That said, being able to find filters based on the type of input the accept sounds useful. It would be better to provide that is a list of submenus. In fact, ParaView could automatically generate such lists as filters already have to declare what inputs are valid.

Whatever naming rules we have, they should place the most descriptive rule first. That way a user can look at a list of filters and scan down the leftmost word to get an indication of what the filter does.

1 Like

Hi there,

I updated the category / renaming proposition.

I definitely missed those points at first place, but I find them really accurate. My new suggestion goes in this direction (at least I tried to).

I think this rename is worse.

I would make “Array” singular for these.

Thanks Cory for those points!

@Kenneth_Moreland I would be happy to have your input on my last update.

I think these are looking much better.

Is the list you posted truncated? I notice that the list ends with the line ## Statistics, but no filters are listed under that. I didn’t bother to go through all the existing filters, but I am not seeing Clean anywhere. (Speaking of which, I’ve complained for a while about having multiple clean filters (#18569). If the clean filters are not consolidated, perhaps you can think of names to distinguish what you would use when.)

Yes indeed, it is a truncated list. To be exact: I did not expand already existing categories (like Statistics).

Also, for a first step I worked on a subset of filter, and I did not considerate most filters that modify mesh (like Clean, or Clip).

Thanks everyone for your feedback!

I will go ahead on the implementation.

Just a heads up, CTH is either a rectilinear mesh code or AMR. It can be either.

1 Like