CaviTracer: clearer parameter names, per-residue lining, and output-path fixes

[briza81]

1. Renamed parameters (breaking)
r1 → surf_radius, r2 → inner_radius throughout the code, WITHOUT ALIASES, so existing scripts passing r1=/r2= now raise TypeError.

2. Signature slimmed; advanced options are keyword-only
Six rarely-used arguments moved out of the calcChannels signature into **kwargs, defaulted from a CHANNELS_ADVANCED_OPTIONS table: restrict_channels_to_start_point, min_enclosure, max_peel_depth, edge_cost, weighted_cache, weighted_mouth_depth. Unknown keywords now raise TypeError instead of being silently ignored, so a misspelled option is reported rather than falling back to its default. All six remain documented.

3. truncate_at_surface removed — truncation is now unconditional
Channels that surface, run along the outside and re-enter are artifacts, so the switch that could produce them is gone. Surface tetrahedra are always absorbing, and similarity/route_tolerance (previously "only used when truncate_at_surface is True") now always apply.

4. Lining residues read per residue, not per CA atom

getObjectResidueNames / getSurfaceCavityResidueNames and their wrappers previously selected name CA, which dropped nucleic acids, ligands, cofactors and ions from every lining report and raised AttributeError when a channel was lined by no protein (e.g. a ribosome). Residues now come from the hierarchical view.

• Labels carry the chain ID: ASP108:A. New include_chain=False restores the old ASP108.
• one_letter_aa translates only amino acids and nucleotides; ligands and ions keep their component ID (previously AAMAP turned the ion K into LYS and SAM into M).
• An object with no lining is reported as channelN: None instead of being skipped, so the returned list keeps one entry per object.

5. Lining distance measured from the object surface
The criterion is now |v − x| <= r + distA rather than distA from the probe centre, so the reach past the wall no longer varies with local probe width (previously it was distA − r: a second shell where the object is narrow, the wall missed entirely where it is wide). distA default changes 4 → 2.5, which keeps channel reports close to their previous size. Channel/pore radii come from the radius spline, which also removes the repeated PDB re-analysis per channel — roughly 5× faster. Cavity vertices carry no radius, so the inscribed radius is recomputed against the tessellation atoms (water excluded); a negative radius is reported as a mismatch between cavities and atoms rather than clamped.

6. Output file naming fixed
Per-object files were named by filename.replace('.pqr', '_chl0.pqr'), which rewrites the extension anywhere in the path. Three failure modes: an output directory named run.pqr/ was renamed along with the file (write fails after the combined file was already written); a name with no extension matched neither replace, so every object overwrote the previous one and the combined file; a name with both extensions was numbered twice. New _numberedPath() uses Path.with_name() and touches only the file's own name. Also fixes selectChannelBySelection, which split on _channel while the writer had long emitted _chl.

7. Smaller cleanups
VDW_RADII lifted to module level and getVdwRadii made a static method; shared _kdTree, _requireCoords, _sampleObjectSpheres, _channelRecords helpers replacing duplicated bodies; the dead try/except AttributeError around getCoords (unreachable — getCoords raises TypeError) removed from four entry points; an undefined forbidden NameError in scanChannelParameters's error path fixed;

[briza81]

@karolamik13 as agreed today, minor modifications, some fixes etc, for your review. Bottleneck argument stays, as it could still have a role; just improved its description. From my side, I consider this a prototype of the (semi)-final version.