sim.loc module

The module loc provides classes to describe location in the simulation world. The instance is mutatable, use clone() to create a copy and make independent changes.

To write your own location class, your class must extend sim.loc.LOC abstract base class and provide implementation to the abstract methods.

Note

• Created by: CH Foh (2021)

List of Classes

LOC

This is the base location class. It mainly defines specification.

CartesianXY

It is suitable for a flat world. It uses (x,y) location in Cartesian coordinate system to describe a location, where x and y are integer.

ScreenXY

It is suitable for a flat world. It uses (x,y) location in Computer Screen coordinate system to describe a location, where x and y are integer. In Computer Screen coordinate system, x increases rightward like Cartesian, but ‘y’ increases downward which is opposite of Cartesian.

Origin

It is a constant origin location, that is (0,0,0) in a 3D world.

---

class sim.loc.LOC

Bases: abc.ABC

This is an abstract class for location. All location classes must extend this class. It has several abstract methods to be reimplemented.

Methods

azimuth_to(other)	This function the azimuth angle to other viewed from this location.
clone()	This function returns a clone of this instance.
distance_to(other)	This function returns how far it is from other.
exactly_same_as(other)	This function returns whether it is exactly at the same location as other.
get_xy()	This function returns (x,y) tuple.
get_xyz()	This function returns (x,y,z) tuple.
move_to(other[, fraction])	This function moves this location towards other where the new location to move to is a fraction of the two locations.
move_towards(other, distance)	This function moves this location towards other for a specific distance.
rotate_azimuth(angle)	This function rotates the location about the origin by the given azimuth angle.
shift(other)	This function shifts the location by other.

abstract __init__()

This is an abstract constructor to be reimplemented. Calling to super() is unnecessary.

abstract clone()

This function returns a clone of this instance. This is an abstract method which should be explicitly reimplemented.

abstract distance_to(other) → float

This function returns how far it is from other. This is an abstract method which should be explicitly reimplemented.

abstract exactly_same_as(other) → bool

This function returns whether it is exactly at the same location as other. This function is only suitable to locations using integers. For float locations, use distance_to instead. This is an abstract method which should be explicitly reimplemented.

abstract move_to(other, fraction: float = 1.0)

This function moves this location towards other where the new location to move to is a fraction of the two locations. This is an abstract method which should be explicitly reimplemented.

Parameters

otheran instance of extended LOC

The point to move towards.

fractionfloat

The fraction (between 0 and 1) of distance to move to. If fraction=0, the new location is its original location. If fraction=1, the new location is the location of other. If fraction=0.5, the new location is the mid-point between the two points.

abstract move_towards(other, distance: float)

This function moves this location towards other for a specific distance. This is an abstract method which should be explicitly reimplemented.

Parameters

otheran instance of extended LOC

The point to move towards.

distancefloat

The distance to move towards other.

abstract get_xy()

This function returns (x,y) tuple.

abstract get_xyz()

This function returns (x,y,z) tuple.

abstract azimuth_to(other)

This function the azimuth angle to other viewed from this location. This is an abstract method which should be explicitly reimplemented.

Parameters

otheran instance of extended LOC

The azimuth angle viewing from this point to other.

Returns

float

The azimuth angle viewing from this location to other.

abstract rotate_azimuth(angle)

This function rotates the location about the origin by the given azimuth angle. This is an abstract method which should be explicitly reimplemented.

Parameters

anglefloat

The angle (in degrees) to rotate. A positive value indicates rotating clockwise, and a negative value indicates anti-clockwise.

abstract shift(other)

This function shifts the location by other. This is an abstract method which should be explicitly reimplemented.

Parameters

otheran instance of extended LOC

The offset given by other to shift this location to.

class sim.loc.ScreenXY(x: int = 0, y: int = 0, xy=None)

Bases: sim.loc.LOC

This is a location class used to describe location in (x,y) in screen coordinate system, and both x and y are an integer.

In screen coordinate system, the left-top is (0,0), and the values increase moving rightward and downward.

Methods

azimuth_to(other)	This function returns the azimuth angle to other viewed from this location.
clone()	This method returns a clone of this object.
distance_to(other)	This function returns how far it is from other.
exactly_same_as(other)	This function returns whether it is exactly at the same location as other.
get_xy()	This function returns (x,y) tuple.
get_xyz()	This function returns (x,y,z) tuple.
move_to(other[, fraction])	See the description in base class for detail.
move_towards(other, distance)	See the description in base class for detail.
rotate_azimuth(angle)	This function rotates the location about the origin by the given azimuth angle.
shift(other)	This function shifts the location by other.

__init__(x: int = 0, y: int = 0, xy=None)

This is the constructor.

Parameters

x, yint, default=0

xy(int,int), default=None

The x and y coordinates in screen coordinate system. The input xy is the (x,y) tuple. If it is given, it will be used for the location. Otherwise, the x and y inputs will be used by default.

clone()

This method returns a clone of this object.

Returns

sim.loc.ScreenXY

The cloned object.

exactly_same_as(other) → bool

This function returns whether it is exactly at the same location as other.

get_xy()

This function returns (x,y) tuple.

get_xyz()

This function returns (x,y,z) tuple.

distance_to(other: sim.loc.ScreenXY) → float

This function returns how far it is from other.

move_to(other: sim.loc.ScreenXY, fraction: float = 1.0)

See the description in base class for detail.

move_towards(other: sim.loc.ScreenXY, distance: float)

See the description in base class for detail.

azimuth_to(other)

This function returns the azimuth angle to other viewed from this location.

rotate_azimuth(angle)

This function rotates the location about the origin by the given azimuth angle.

shift(other)

This function shifts the location by other.

class sim.loc.CartesianXY(x: int = 0, y: int = 0)

Bases: sim.loc.LOC

This is a location class used to describe location in (x,y) in Cartesian coordinate system, and both x and y are an integer.

Methods

azimuth_to(other)	This function returns the azimuth angle to other viewed from this location.
clone()	This method returns a clone of this obect.
distance_to(other)	This function returns how far it is from other.
exactly_same_as(other)	This function returns whether it is exactly at the same location as other.
get_xy()	This function returns (x,y) tuple.
get_xyz()	This function returns (x,y,z) tuple.
move_to(other[, fraction])	See the description in base class for detail.
move_towards(other, distance)	See the description in base class for detail.
rotate_azimuth(angle)	This function rotates the location about the origin by the given azimuth angle.
shift(other)	This function shifts the location by other.

__init__(x: int = 0, y: int = 0)

This is the constructor.

Parameters

x, yint

The x and y coordinates in Cartesian coordinate system.

clone()

This method returns a clone of this obect.

Returns

sim.loc.CartesianXY

The cloned object.

exactly_same_as(other) → bool

This function returns whether it is exactly at the same location as other.

get_xy()

This function returns (x,y) tuple.

get_xyz()

This function returns (x,y,z) tuple.

distance_to(other: sim.loc.CartesianXY) → float

This function returns how far it is from other.

move_to(other: sim.loc.CartesianXY, fraction: float = 1.0)

See the description in base class for detail.

move_towards(other: sim.loc.CartesianXY, distance: float)

See the description in base class for detail.

azimuth_to(other)

This function returns the azimuth angle to other viewed from this location.

rotate_azimuth(angle)

This function rotates the location about the origin by the given azimuth angle.

shift(other)

This function shifts the location by other.