'clip' input vs. output

[Tristan Croll]

The following bug report has been submitted:
Platform:        Linux-6.8.0-51-generic-x86_64-with-glibc2.35
ChimeraX Version: 1.9 (2024-12-11 19:11:19 UTC)
Description
Not sure if this is a bug or just my misunderstanding, but it took a while for me to figure out how to apply the results of "clip list" to reproduce the same scene in a .cxc file. I think I get it now, but reporting because I suspect it may be a reasonably common source of confusion for others. Directly applying the logged results of "clip list", e.g.:

{{{
clip list
Using 2 clip planes: 
far offset 31.077, axis 0.000,0.000,1.000, point 83,81.31,31.7) 
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)

clip far 31.077 axis 0,0,1 pos 83,81.31,31.7
clip near -6.5273 axis 0,0,-1 pos 83,81.31,69.31
}}}

... does *not* reproduce the scene. After some trial and error I realised that ignoring the offset output and just doing e.g.

{{{
clip far 0 axis 0,0,1 pos 83,81.31,31.7
clip near 0 axis 0,0,-1 pos 83,81.31,69.31
}}}

... is what works. Without looking at code, my guess is that `clip list` reports the offset relative to the camera position, as opposed to `clip near`, `clip far` etc. which apply it relative to the `position` argument? 

Log:
Startup Messages  
---  
note | available bundle cache has not been initialized yet  
  
Running command "isolde shorthand"  

> isolde shorthand
    
    
    Initialising ISOLDE-specific command aliases:
    Alias	Equivalent full command
    -------------------------------------------------
    st	isolde step {arguments}
    aw	isolde add water {arguments}
    awsf	isolde add water {arguments} sim false
    al	isolde add ligand {arguments}
    aa	isolde add aa $1 sel {arguments}
    ht	isolde mod his sel {arguments}
    so	setattr sel atoms occupancy {arguments}
    ab	isolde adjust bfactors {arguments}
    ss	isolde sim start sel
    rt	isolde release torsions sel {arguments}
    rd	isolde release distances sel {arguments}
    ra	rd; rt
    pf	isolde pepflip sel
    cf	isolde cisflip sel
    cbb	color bfactor {arguments}
    cbo	color byattr occupancy {arguments}
    cbc	color {arguments} bychain; color {arguments} byhet
    cs	clipper set contourSensitivity {arguments}
    

  
UCSF ChimeraX version: 1.9 (2024-12-11)  
© 2016-2024 Regents of the University of California. All rights reserved.  
How to cite UCSF ChimeraX  

> open 3io0

3io0 title:  
Crystal structure of EtuB from Clostridium kluyveri [more info...]  
  
Chain information for 3io0 #1  
---  
Chain | Description | UniProt  
A | EtuB protein | A5N734_CLOK5 75-304  
  
3io0 mmCIF Assemblies  
---  
1| author_and_software_defined_assembly  
  
Running command "ui tool show "Side View""  

> ui tool show "Side View"

> clip list

Using 2 clip planes:  
far offset 15.538, axis 0.000,0.000,1.000, point 83,81.31,47.24)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> clif far 15.538 axis 0.000,0.000,1.000 pos 83,81.31,47.24

Unknown command: clif far 15.538 axis 0.000,0.000,1.000 pos 83,81.31,47.24  

> clip far 15.538 axis 0.000,0.000,1.000 position 83,81.31,47.24

> usage clip

clip [near near] [far far] [front front] [back back] [position center point]
[axis an axis vector] [coordinateSystem a coordinate-system]  
— set clip planes  
near: off or a number  
far: off or a number  
front: off or a number  
back: off or a number

clip list  
— List active clip planes

clip model models [clipping]  
— Turn off clipping for individual models.  
clipping: true or false

clip off  
— Turn off all clip planes  

> clip far 15.538 axis 0.000,0.000,1.000 position 83,81.31,47.24

> clip list

Using 2 clip planes:  
far offset 31.077, axis 0.000,0.000,1.000, point 83,81.31,31.7)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> clip far 0 axis 0.000,0.000,1.000 position 83,81.31,47.24

> clip list

Using 2 clip planes:  
far offset 15.539, axis 0.000,0.000,1.000, point 83,81.31,47.24)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> clip far 0 axis 0.000,0.000,1.000 position 83,81.31,47.24

> clip far 15.538

> clip far 0 position 83,81.31,47.24

[Repeated 1 time(s)]

> clip list

Using 2 clip planes:  
far offset 15.539, axis 0.000,0.000,1.000, point 83,81.31,47.24)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> camera ortho

> clip list

Using 2 clip planes:  
far offset 15.539, axis 0.000,0.000,1.000, point 83,81.31,47.24)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> usage clip list

clip list  
— List active clip planes  

> clip list

Using 2 clip planes:  
far offset 9.6349, axis 0.000,0.000,1.000, point 83,81.31,53.14)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> clip far 0 position 03,81.31,53,14

Invalid "position" argument: Expected 3 floats or object specifier  

> clip far 0 position 83,81.31,53,14

Invalid "position" argument: Expected 3 floats or object specifier  

> clip far 0 position 83,81.31,53.14

[Repeated 1 time(s)]

> clip list

Using 2 clip planes:  
far offset 9.6388, axis 0.000,0.000,1.000, point 83,81.31,53.14)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> clip far 0 axis 0.000,0.000,1.000 position 83,81.31,47.24

> clip list

Using 2 clip planes:  
far offset 15.539, axis 0.000,0.000,1.000, point 83,81.31,47.24)  
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)  

> clip near 0 axis 0,0,-1 position 83,81.31,69.31




OpenGL version: 3.3.0 NVIDIA 535.216.03
OpenGL renderer: NVIDIA GeForce RTX 3070/PCIe/SSE2
OpenGL vendor: NVIDIA Corporation

Python: 3.11.4
Locale: en_GB.UTF-8
Qt version: PyQt6 6.7.1, Qt 6.7.1
Qt runtime version: 6.7.3
Qt platform: xcb

XDG_SESSION_TYPE=x11
DESKTOP_SESSION=ubuntu
XDG_SESSION_DESKTOP=ubuntu
XDG_CURRENT_DESKTOP=ubuntu:GNOME
DISPLAY=:1
Manufacturer: Dell Inc.
Model: XPS 8950
OS: Ubuntu 22.04
Architecture: 64bit ELF
Virtual Machine: none
CPU: 20 12th Gen Intel(R) Core(TM) i7-12700
Cache Size: 25600 KB
Memory:
	               total        used        free      shared  buff/cache   available
	Mem:            31Gi        19Gi       2.3Gi       590Mi       8.9Gi         9Gi
	Swap:          2.0Gi       2.0Gi       8.0Mi

Graphics:
	0000:01:00.0 VGA compatible controller [0300]: NVIDIA Corporation GA104 [GeForce RTX 3070 Lite Hash Rate] [10de:2488] (rev a1)	
	Subsystem: Dell GA104 [GeForce RTX 3070 Lite Hash Rate] [1028:c903]	
	Kernel driver in use: nvidia

Installed Packages:
    alabaster: 1.0.0
    anyio: 4.7.0
    appdirs: 1.4.4
    asttokens: 3.0.0
    auditwheel: 6.1.0
    autocommand: 2.2.2
    babel: 2.16.0
    backports.tarfile: 1.2.0
    beautifulsoup4: 4.12.3
    blockdiag: 3.0.0
    blosc2: 3.0.0
    build: 1.2.1
    certifi: 2024.8.30
    cftime: 1.6.4.post1
    charset-normalizer: 3.4.0
    ChimeraX-AddCharge: 1.5.18
    ChimeraX-AddH: 2.2.6
    ChimeraX-AlignmentAlgorithms: 2.0.2
    ChimeraX-AlignmentHdrs: 3.5
    ChimeraX-AlignmentMatrices: 2.1
    ChimeraX-Alignments: 2.16.1
    ChimeraX-AlphaFold: 1.0.1
    ChimeraX-AltlocExplorer: 1.1.2
    ChimeraX-AmberInfo: 1.0
    ChimeraX-Arrays: 1.1
    ChimeraX-Atomic: 1.58.8
    ChimeraX-AtomicLibrary: 14.1.11
    ChimeraX-AtomSearch: 2.0.1
    ChimeraX-AxesPlanes: 2.4
    ChimeraX-BasicActions: 1.1.2
    ChimeraX-BILD: 1.0
    ChimeraX-BlastProtein: 3.0.0
    ChimeraX-BondRot: 2.0.4
    ChimeraX-BugReporter: 1.0.1
    ChimeraX-BuildStructure: 2.13.1
    ChimeraX-Bumps: 1.0
    ChimeraX-BundleBuilder: 1.4.0
    ChimeraX-ButtonPanel: 1.0.1
    ChimeraX-CageBuilder: 1.0.1
    ChimeraX-CellPack: 1.0
    ChimeraX-Centroids: 1.4
    ChimeraX-ChangeChains: 1.1
    ChimeraX-CheckWaters: 1.4
    ChimeraX-ChemGroup: 2.0.1
    ChimeraX-Clashes: 2.3
    ChimeraX-Clipper: 0.24.0
    ChimeraX-ColorActions: 1.0.5
    ChimeraX-ColorGlobe: 1.0
    ChimeraX-ColorKey: 1.5.6
    ChimeraX-CommandLine: 1.2.5
    ChimeraX-ConnectStructure: 2.0.1
    ChimeraX-Contacts: 1.0.1
    ChimeraX-Core: 1.9
    ChimeraX-CoreFormats: 1.2
    ChimeraX-coulombic: 1.4.4
    ChimeraX-Crosslinks: 1.0
    ChimeraX-Crystal: 1.0
    ChimeraX-CrystalContacts: 1.0.1
    ChimeraX-DataFormats: 1.2.3
    ChimeraX-Dicom: 1.2.6
    ChimeraX-DistMonitor: 1.4.2
    ChimeraX-DockPrep: 1.1.3
    ChimeraX-Dssp: 2.0
    ChimeraX-EMDB-SFF: 1.0
    ChimeraX-ESMFold: 1.0
    ChimeraX-FileHistory: 1.0.1
    ChimeraX-FunctionKey: 1.0.1
    ChimeraX-Geometry: 1.3
    ChimeraX-gltf: 1.0
    ChimeraX-Graphics: 1.4.1
    ChimeraX-Hbonds: 2.5
    ChimeraX-Help: 1.3
    ChimeraX-HKCage: 1.3
    ChimeraX-IHM: 1.1
    ChimeraX-ImageFormats: 1.2
    ChimeraX-IMOD: 1.0
    ChimeraX-IO: 1.0.3
    ChimeraX-ISOLDE: 1.9
    ChimeraX-ItemsInspection: 1.0.1
    ChimeraX-IUPAC: 1.0
    ChimeraX-KVFinder: 1.2.1
    ChimeraX-Label: 1.1.14
    ChimeraX-LinuxSupport: 1.0.1
    ChimeraX-ListInfo: 1.2.2
    ChimeraX-Log: 1.2
    ChimeraX-LookingGlass: 1.1
    ChimeraX-Maestro: 1.9.1
    ChimeraX-Map: 1.3
    ChimeraX-MapData: 2.0
    ChimeraX-MapEraser: 1.0.1
    ChimeraX-MapFilter: 2.0.1
    ChimeraX-MapFit: 2.0
    ChimeraX-MapSeries: 2.1.1
    ChimeraX-Markers: 1.0.1
    ChimeraX-Mask: 1.0.2
    ChimeraX-MatchMaker: 2.1.6
    ChimeraX-MCopy: 1.0
    ChimeraX-MDcrds: 2.7.2
    ChimeraX-MedicalToolbar: 1.1
    ChimeraX-Meeting: 1.0.1
    ChimeraX-MLP: 1.1.1
    ChimeraX-mmCIF: 2.14.2
    ChimeraX-MMTF: 2.2
    ChimeraX-ModelArchive: 1.0
    ChimeraX-Modeller: 1.5.18
    ChimeraX-ModelPanel: 1.5
    ChimeraX-ModelSeries: 1.0.1
    ChimeraX-Mol2: 2.0.3
    ChimeraX-Mole: 1.0
    ChimeraX-Morph: 1.0.2
    ChimeraX-MouseModes: 1.2
    ChimeraX-Movie: 1.0
    ChimeraX-MutationScores: 1.0
    ChimeraX-Neuron: 1.0
    ChimeraX-Nifti: 1.2
    ChimeraX-NMRSTAR: 1.0.2
    ChimeraX-NRRD: 1.2
    ChimeraX-Nucleotides: 2.0.3
    ChimeraX-OpenCommand: 1.14
    ChimeraX-OrthoPick: 1.0.1
    ChimeraX-PDB: 2.7.6
    ChimeraX-PDBBio: 1.0.1
    ChimeraX-PDBLibrary: 1.0.4
    ChimeraX-PDBMatrices: 1.0
    ChimeraX-PickBlobs: 1.0.1
    ChimeraX-Positions: 1.0
    ChimeraX-PresetMgr: 1.1.2
    ChimeraX-PubChem: 2.2
    ChimeraX-QScore: 1.2
    ChimeraX-ReadPbonds: 1.0.1
    ChimeraX-Registration: 1.1.2
    ChimeraX-RemoteControl: 1.0
    ChimeraX-RenderByAttr: 1.6.2
    ChimeraX-RenumberResidues: 1.1
    ChimeraX-ResidueFit: 1.0.1
    ChimeraX-RestServer: 1.3.1
    ChimeraX-RNALayout: 1.0
    ChimeraX-RotamerLibMgr: 4.0
    ChimeraX-RotamerLibsDunbrack: 2.0
    ChimeraX-RotamerLibsDynameomics: 2.0
    ChimeraX-RotamerLibsRichardson: 2.0
    ChimeraX-SaveCommand: 1.5.1
    ChimeraX-SchemeMgr: 1.0
    ChimeraX-SDF: 2.0.2
    ChimeraX-Segger: 1.0
    ChimeraX-Segment: 1.0.1
    ChimeraX-Segmentations: 3.5.6
    ChimeraX-SelInspector: 1.0
    ChimeraX-SeqView: 2.14
    ChimeraX-Shape: 1.0.1
    ChimeraX-Shell: 1.0.1
    ChimeraX-Shortcuts: 1.2.0
    ChimeraX-ShowSequences: 1.0.3
    ChimeraX-SideView: 1.0.1
    ChimeraX-SimilarStructures: 1.0.1
    ChimeraX-Smiles: 2.1.2
    ChimeraX-SmoothLines: 1.0
    ChimeraX-SpaceNavigator: 1.0
    ChimeraX-StdCommands: 1.18.1
    ChimeraX-STL: 1.0.1
    ChimeraX-Storm: 1.0
    ChimeraX-StructMeasure: 1.2.1
    ChimeraX-Struts: 1.0.1
    ChimeraX-Surface: 1.0.1
    ChimeraX-SwapAA: 2.0.1
    ChimeraX-SwapRes: 2.5
    ChimeraX-TapeMeasure: 1.0
    ChimeraX-TaskManager: 1.0
    ChimeraX-Test: 1.0
    ChimeraX-Toolbar: 1.2.3
    ChimeraX-ToolshedUtils: 1.2.4
    ChimeraX-Topography: 1.0
    ChimeraX-ToQuest: 1.0
    ChimeraX-Tug: 1.0.1
    ChimeraX-UI: 1.41
    ChimeraX-Umap: 1.0
    ChimeraX-uniprot: 2.3.1
    ChimeraX-UnitCell: 1.0.1
    ChimeraX-ViewDockX: 1.4.4
    ChimeraX-VIPERdb: 1.0
    ChimeraX-Vive: 1.1
    ChimeraX-VolumeMenu: 1.0.1
    ChimeraX-vrml: 1.0
    ChimeraX-VTK: 1.0
    ChimeraX-WavefrontOBJ: 1.0
    ChimeraX-WebCam: 1.0.2
    ChimeraX-WebServices: 1.1.4
    ChimeraX-Zone: 1.0.1
    colorama: 0.4.6
    comm: 0.2.2
    contourpy: 1.3.1
    cxservices: 1.2.3
    cycler: 0.12.1
    Cython: 3.0.10
    debugpy: 1.8.9
    decorator: 5.1.1
    distro: 1.9.0
    docutils: 0.21.2
    executing: 2.1.0
    filelock: 3.15.4
    fonttools: 4.55.3
    funcparserlib: 2.0.0a0
    glfw: 2.8.0
    grako: 3.16.5
    h11: 0.14.0
    h5py: 3.12.1
    html2text: 2024.2.26
    httpcore: 1.0.7
    httpx: 0.28.1
    idna: 3.10
    ihm: 1.3
    imagecodecs: 2024.6.1
    imagesize: 1.4.1
    importlib_metadata: 8.0.0
    importlib_resources: 6.4.0
    inflect: 7.3.1
    ipykernel: 6.29.5
    ipython: 8.26.0
    ipywidgets: 8.1.5
    jaraco.context: 5.3.0
    jaraco.functools: 4.0.1
    jaraco.text: 3.12.1
    jedi: 0.19.1
    Jinja2: 3.1.4
    jupyter_client: 8.6.2
    jupyter_core: 5.7.2
    jupyterlab_widgets: 3.0.13
    kiwisolver: 1.4.7
    line_profiler: 4.1.3
    lxml: 5.2.2
    lz4: 4.3.3
    MarkupSafe: 3.0.2
    matplotlib: 3.9.2
    matplotlib-inline: 0.1.7
    more-itertools: 10.3.0
    msgpack: 1.0.8
    ndindex: 1.9.2
    nest-asyncio: 1.6.0
    netCDF4: 1.6.5
    networkx: 3.3
    nibabel: 5.2.0
    nptyping: 2.5.0
    numexpr: 2.10.2
    numpy: 1.26.4
    openvr: 1.26.701
    ordered-set: 4.1.0
    packaging: 23.2
    packaging: 24.1
    ParmEd: 4.2.2
    parso: 0.8.4
    pep517: 0.13.1
    pexpect: 4.9.0
    pillow: 10.4.0
    pip: 24.2
    pkginfo: 1.11.1
    platformdirs: 4.3.6
    platformdirs: 4.2.2
    prompt_toolkit: 3.0.48
    psutil: 6.0.0
    ptyprocess: 0.7.0
    pure_eval: 0.2.3
    py-cpuinfo: 9.0.0
    pycollada: 0.8
    pydicom: 2.4.4
    pyelftools: 0.31
    Pygments: 2.18.0
    pynmrstar: 3.3.4
    pynrrd: 1.0.0
    PyOpenGL: 3.1.7
    PyOpenGL-accelerate: 3.1.7
    pyopenxr: 1.0.3401
    pyparsing: 3.2.0
    pyproject_hooks: 1.2.0
    PyQt6-commercial: 6.7.1
    PyQt6-Qt6: 6.7.3
    PyQt6-WebEngine-commercial: 6.7.0
    PyQt6-WebEngine-Qt6: 6.7.3
    PyQt6-WebEngineSubwheel-Qt6: 6.7.3
    PyQt6_sip: 13.8.0
    python-dateutil: 2.9.0.post0
    pytz: 2024.2
    pyzmq: 26.2.0
    qtconsole: 5.5.2
    QtPy: 2.4.2
    qtshim: 1.0
    RandomWords: 0.4.0
    requests: 2.32.3
    scipy: 1.14.0
    Send2Trash: 1.8.3
    SEQCROW: 1.8.17
    setuptools: 72.1.0
    sfftk-rw: 0.8.1
    six: 1.16.0
    sniffio: 1.3.1
    snowballstemmer: 2.2.0
    sortedcontainers: 2.4.0
    soupsieve: 2.6
    Sphinx: 8.0.2
    sphinx-autodoc-typehints: 2.2.3
    sphinxcontrib-applehelp: 2.0.0
    sphinxcontrib-blockdiag: 3.0.0
    sphinxcontrib-devhelp: 2.0.0
    sphinxcontrib-htmlhelp: 2.1.0
    sphinxcontrib-jsmath: 1.0.1
    sphinxcontrib-qthelp: 2.0.0
    sphinxcontrib-serializinghtml: 2.0.0
    stack-data: 0.6.3
    superqt: 0.6.3
    tables: 3.10.1
    tcia_utils: 1.5.1
    tifffile: 2024.7.24
    tinyarray: 1.2.4
    tomli: 2.0.1
    tornado: 6.4.2
    traitlets: 5.14.3
    typeguard: 4.3.0
    typing_extensions: 4.12.2
    typing_extensions: 4.12.2
    tzdata: 2024.2
    urllib3: 2.2.3
    wcwidth: 0.2.13
    webcolors: 24.6.0
    wheel: 0.43.0
    wheel: 0.43.0
    wheel-filename: 1.4.1
    widgetsnbextension: 4.0.13
    zipp: 3.19.2

[Tom Goddard]

The clip list command outputs a point on each clip plane

clip list
Using 2 clip planes: 
far offset 31.077, axis 0.000,0.000,1.000, point 83,81.31,31.7) 
near offset -6.5273, axis 0.000,0.000,-1.000, point 83,81.31,69.31)

The clip command has a "position" option and while that sounds like it might be a point on the plane it is not. It is actually the reference position relative to offsets that specify the plane position. This is described in the clip documentation "The offsets are relative to the 'position' reference point, if given."

I've renamed the clip list "point" output to "point on plane" to help clarify this. But without reading the "clip" documentation I doubt a user will guess that the clip "position" option is a reference point to which offsets apply to set the clip plane distance.

I guess I could add a "reference position" output to clip list in addition to the point on plane, but I don't think this will help because the basic confusion is that that the "position" option in the clip command is the reference position that offsets are applied to which is only the actual position of the plane if the offset is 0. I'm afraid the only real solution is reading the clip documentation.