schrodinger.project.surface_map_utils module

class schrodinger.project.surface_map_utils.ProjectMapRef(entry_id: int, surface_name: str)

Bases: object

Identify one map surface in a project entry.

entry_id: int
surface_name: str
__init__(entry_id: int, surface_name: str) → None
class schrodinger.project.surface_map_utils.MapReference(value: pathlib.Path | ProjectMapRef)

Bases: object

Identify a map file or one map surface in a project entry.

value: pathlib.Path | ProjectMapRef
__init__(value: pathlib.Path | ProjectMapRef) → None
schrodinger.project.surface_map_utils.get_selected_maps(project: Project) → list[ProjectSurface]

Get volume-based surfaces from all map-only entries selected in the Project Table.

Parameters:

project – The project to get surfaces from.

Raises:

ValueError – If the project is None.

Returns:

A list of ProjectSurface objects corresponding to the volume-based surfaces for map-only entries in the project.

schrodinger.project.surface_map_utils.get_included_maps(project: Project) → list[ProjectSurface]

Get volume-based surfaces from all map-only entries included in the Workspace.

Parameters:

project – The project to get surfaces from.

Raises:

ValueError – If the project is None.

Returns:

A list of ProjectSurface objects corresponding to the volume-based surfaces for map-only entries in the project.

schrodinger.project.surface_map_utils.get_map_by_entry_id(project: Project, entry_id: int) → list[ProjectSurface]

Get volume-based surfaces for a given map-only entry with the specified entry ID.

Parameters:

  • project – The project to get surfaces from.

  • entry_id – The entry ID to look up.

Raises:

ValueError – If the project is None or if the entry ID is not found in the project or if the entry ID does not correspond to a map-only entry.

Returns:

A list of ProjectSurface objects corresponding to the volume-based surfaces for the given map-only entry.

schrodinger.project.surface_map_utils.export_map_surface(project: Project, entry_id: int, surface_name: str, path: Path) → None

Export the named map surface of a map-only entry to a file.

Parameters:

  • project – The project to get the surface from.

  • entry_id – The entry ID of the map-only entry.

  • surface_name – The name of the surface to export.

  • path – The destination file path for the exported map.

Raises:

ValueError – If the project is None, the entry is not a map-only entry, or no surface with surface_name is found.

schrodinger.project.surface_map_utils.write_map_file(reference: MapReference, dest: PathLike, *, project: Project) → Path

Write MapReference to a map file at dest, copying a browsed file (skipping a no-op self-copy) or exporting the selected project surface.

Parameters:

  • reference – The map reference to write.

  • dest – Destination file path.

  • project – Project used to export a project-surface selection. It is not consulted for a file selection.

Returns:

The destination path.

schrodinger.project.surface_map_utils.stage_map_reference(reference: MapReference | None, task, *, project_map_filename: str, path_basename: str, not_set_msg: str, staging_failed_msg: str) → tuple[bool, str] | None

Stage a panel’s resolved map into its task directory.

Copies a browsed file (destination path_basename plus the source extension) or exports a selected project map (destination project_map_filename, resolving the active project here), then records the staged file on task.input.map_file. Panels call this from a task preprocessor after the task directory exists; centralizing it keeps the project resolution, staging, and error handling identical across panels.

Parameters:

  • reference – The resolved map reference, or None if none selected.

  • task – The task providing getTaskFilename and input.map_file.

  • project_map_filename – Destination filename for a project-map export.

  • path_basename – Destination basename for a browsed file; the source file’s extension is appended.

  • not_set_msg – Failure message returned when reference is None.

  • staging_failed_msg – Failure message prefix used when staging raises.

Returns:

None on success, or (False, message) on failure, matching the task-preprocessor contract.